Document exceptions/behavior of ChannelWriter writing after writer is completed.

[poizan42]

Issue description

The documentation for ChannelWriter<T>.(TryWrite|WaitToWriteAsync|WriteAsync) does not say what happens in case the writer has been completed. In fact WaitToWriteAsync throws the exception set in ChannelWriter.Complete(Exception) if specified while returing false if no exception was specified. In contrast WriteAsync always throws a System.Threading.Channels.ChannelClosedException, optionally with the supplied exception as its InnerException. Neither of these are documented as throwing any exceptions.

The following program generates the same output on .NET 6.0 and .NET Framework 4.8

Test program source

using System;
using System.Threading.Channels;
using System.Threading.Tasks;

namespace ChannelTest;

public class Program
{
    private static string GetExceptionDescriptionWithInnerExceptions(Exception e)
    {
        if (e.InnerException != null)
            return $"{e.GetType().FullName}: {e.Message}  ---> {GetExceptionDescriptionWithInnerExceptions(e.InnerException)}";
        else
            return $"{e.GetType().FullName}: {e.Message}";
    }
    private static void PrintResultOrError(string op, Func<Task> f)
        => PrintResultOrError(op, async () => { await f(); return "Success"; });
    private static void PrintResultOrError<T>(string op, Func<T> f)
        => PrintResultOrError(op, () => Task.FromResult(f()));
    private static void PrintResultOrError<T>(string op, Func<Task<T>> f)
    {
        try
        {
            T result = f().GetAwaiter().GetResult();
            Console.WriteLine($"{op}: {result}");
        }
        catch (Exception e)
        {
            Console.WriteLine($"{op} failed: {GetExceptionDescriptionWithInnerExceptions(e)}");
        }
    }
    public static void Main(string[] args)
    {
        Console.WriteLine("== Write after complete, unbounded without exception ==");
        TestChannelWriteAfterCompleted(false, null);
        Console.WriteLine();
        Console.WriteLine("== Write after complete, unbounded with exception ==");
        TestChannelWriteAfterCompleted(false, new Exception("Foobar!"));
        Console.WriteLine("== Write after complete, bounded without exception ==");
        TestChannelWriteAfterCompleted(true, null);
        Console.WriteLine();
        Console.WriteLine("== Write after complete, bounded with exception ==");
        TestChannelWriteAfterCompleted(true, new Exception("Foobar!"));
    }

    private static void TestChannelWriteAfterCompleted(bool bounded, Exception? exception)
    {
        Channel<string> channel = bounded ?
            Channel.CreateBounded<string>(new BoundedChannelOptions(5) { FullMode = BoundedChannelFullMode.Wait, SingleReader = true, SingleWriter = true }) :
            Channel.CreateUnbounded<string>(new UnboundedChannelOptions { SingleReader = true, SingleWriter = true });
        channel.Writer.Complete(exception);
        PrintResultOrError("TryWrite", () => channel.Writer.TryWrite("Hello, World!"));
        PrintResultOrError("WaitToWriteAsync", () => channel.Writer.WaitToWriteAsync().AsTask());
        PrintResultOrError("WriteAsync", () => channel.Writer.WriteAsync("World").AsTask());
    }
}

Test program output

== Write after complete, unbounded with exception ==
TryWrite: False
WaitToWriteAsync failed: System.Exception: Foobar!
WriteAsync failed: System.Threading.Channels.ChannelClosedException: The channel has been closed.  ---> System.Exception: Foobar!
== Write after complete, bounded without exception ==
TryWrite: False
WaitToWriteAsync: False
WriteAsync failed: System.Threading.Channels.ChannelClosedException: The channel has been closed.

== Write after complete, bounded with exception ==
TryWrite: False
WaitToWriteAsync failed: System.Exception: Foobar!
WriteAsync failed: System.Threading.Channels.ChannelClosedException: The channel has been closed.  ---> System.Exception: Foobar!

Documentation source: https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System.Threading.Channels/ChannelWriter%601.xml

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

[MichaelDeutschCoding]

I think the WriteAsync throwing an exception makes sense, and does just need appropriate documentation. But to my understanding, I'd assume methods named "Try"Something() that return a bool shouldn't really throw exceptions, but rather should just return false. This feels more like a bug than just a documentation shortcoming.

The only behavior that seems odd is the WaitToWriteAsync when an exception is passed to the Complete() method.

[poizan42]

@MichaelDeutschCoding Completed() is supposed to be used to signal to readers that no more data will be written, so it can be seen as an exceptional conditions to attempt to write to the channel - but it may be the most elegant solution to coordinate ending multiple writers by "poisoning" the writer with a call to Completed().
Normally TryWrite() is used to write in a non-blocking manner to a channel the might be full. With the view that writing to a completed channel is an exceptional condition it might make sense to throw an exception.

However changing the behaviour at this point risks breaking a lot of existing code, so it's probably better to just document the current behaviour.

[MichaelDeutschCoding]

Ok, yeah I agree that makes sense. Also, although the WaitToWriteAsync does return a bool, I misspoke in my previous comment, as it doesn't actually have "Try" in the method name. The TryWrite method (as its name implies) didn't throw any exception in the samples above, but returned false as one would expect.

I'm happy to update the documentation for these if you'd like. Just want to clarify what that would entail:

• WriteAsync
  • add an <exception> element with the ChannelClosedException to its "Docs"
• WaitToWriteAsync
  • We can add the exception to its documentation, but it is a bit weird. Because if the Channel was marked as Complete without any inner exception, then it'll just return false and not throw
  • Update the Returns part to explain that it won't always return false when it can no longer write, but sometimes will throw.

Tagging subscribers to this area: @dotnet/area-system-threading-channels
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Issue description

The documentation for ChannelWriter<T>.(TryWrite|WaitToWriteAsync|WriteAsync) does not say what happens in case the writer has been completed. In fact WaitToWriteAsync throws the exception set in ChannelWriter.Complete(Exception) if specified while returing false if no exception was specified. In contrast WriteAsync always throws a System.Threading.Channels.ChannelClosedException, optionally with the supplied exception as its InnerException. Neither of these are documented as throwing any exceptions.

The following program generates the same output on .NET 6.0 and .NET Framework 4.8

Test program source

using System;
using System.Threading.Channels;
using System.Threading.Tasks;

namespace ChannelTest;

public class Program
{
    private static string GetExceptionDescriptionWithInnerExceptions(Exception e)
    {
        if (e.InnerException != null)
            return $"{e.GetType().FullName}: {e.Message}  ---> {GetExceptionDescriptionWithInnerExceptions(e.InnerException)}";
        else
            return $"{e.GetType().FullName}: {e.Message}";
    }
    private static void PrintResultOrError(string op, Func<Task> f)
        => PrintResultOrError(op, async () => { await f(); return "Success"; });
    private static void PrintResultOrError<T>(string op, Func<T> f)
        => PrintResultOrError(op, () => Task.FromResult(f()));
    private static void PrintResultOrError<T>(string op, Func<Task<T>> f)
    {
        try
        {
            T result = f().GetAwaiter().GetResult();
            Console.WriteLine($"{op}: {result}");
        }
        catch (Exception e)
        {
            Console.WriteLine($"{op} failed: {GetExceptionDescriptionWithInnerExceptions(e)}");
        }
    }
    public static void Main(string[] args)
    {
        Console.WriteLine("== Write after complete, unbounded without exception ==");
        TestChannelWriteAfterCompleted(false, null);
        Console.WriteLine();
        Console.WriteLine("== Write after complete, unbounded with exception ==");
        TestChannelWriteAfterCompleted(false, new Exception("Foobar!"));
        Console.WriteLine("== Write after complete, bounded without exception ==");
        TestChannelWriteAfterCompleted(true, null);
        Console.WriteLine();
        Console.WriteLine("== Write after complete, bounded with exception ==");
        TestChannelWriteAfterCompleted(true, new Exception("Foobar!"));
    }

    private static void TestChannelWriteAfterCompleted(bool bounded, Exception? exception)
    {
        Channel<string> channel = bounded ?
            Channel.CreateBounded<string>(new BoundedChannelOptions(5) { FullMode = BoundedChannelFullMode.Wait, SingleReader = true, SingleWriter = true }) :
            Channel.CreateUnbounded<string>(new UnboundedChannelOptions { SingleReader = true, SingleWriter = true });
        channel.Writer.Complete(exception);
        PrintResultOrError("TryWrite", () => channel.Writer.TryWrite("Hello, World!"));
        PrintResultOrError("WaitToWriteAsync", () => channel.Writer.WaitToWriteAsync().AsTask());
        PrintResultOrError("WriteAsync", () => channel.Writer.WriteAsync("World").AsTask());
    }
}

Test program output

== Write after complete, unbounded with exception ==
TryWrite: False
WaitToWriteAsync failed: System.Exception: Foobar!
WriteAsync failed: System.Threading.Channels.ChannelClosedException: The channel has been closed.  ---> System.Exception: Foobar!
== Write after complete, bounded without exception ==
TryWrite: False
WaitToWriteAsync: False
WriteAsync failed: System.Threading.Channels.ChannelClosedException: The channel has been closed.

== Write after complete, bounded with exception ==
TryWrite: False
WaitToWriteAsync failed: System.Exception: Foobar!
WriteAsync failed: System.Threading.Channels.ChannelClosedException: The channel has been closed.  ---> System.Exception: Foobar!

Documentation source: https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System.Threading.Channels/ChannelWriter%601.xml

Author:	poizan42
Assignees:	-
Labels:	untriaged, Pri3, area-System.Threading.Channels
Milestone:	-

[poizan42]

@MichaelDeutschCoding

• WriteAsync
  I agree, ChannelClosedException should be added as an <exception> element
• WaitToWriteAsync
  Technically it should list System.Exception, but that is not terribly helpful. I think the behaviour should be documented in the <remarks> section.
• TryWrite
  Maybe it should be mentioned in the <remarks> section that it will return false if the channel is completed?

[MichaelDeutschCoding]

The TryWrite does mention that behavior. Doesn't say explicitly why it wasn't able to write, but it does note that it returns false if it wasn't able to write.

You can have a look at #9268 and comment there if you have any suggestions.