[API Proposal]: Add CancellationToken to TextWriter.FlushAsync

[Shane32]

Background and motivation

Some TextWriter implementations such as StreamWriter serve to encode data in a particular format and then write that data to an underlying data stream. The underlying data stream could easily be a file stream or network stream, where it is desired to be able to cancel any pending operation upon either an upstream cancellation (e.g. termination of the HTTP request that initiated such as data transfer) or user request (e.g. user clicks Cancel button).

Some implementations also buffer data before reaching the underlying stream, and without a call to Flush (or AutoFlush = true), do not flush those buffers to the underlying stream. So it is sometimes necessary in these instances to call Flush to ensure that the TextWriter implementation has flushed its buffers to the underlying stream, even if it is not necessary to flush the underlying stream. Typical implementations of Flush however will typically flush their own buffers and then call the Flush method of the underlying stream.

Calling FlushAsync on an underlying data stream can often result in an asynchronous delay while the data is written to disk or sent over the network. However, the method does not provide any means to cancel the underlying write/flush operation.

With the merging of #61898, both TextReader and TextWriter supports cancellation tokens for each of their methods (in some form) except this one.

Note that the Stream.FlushAsync method has an overload with a cancellation token since .NET Standard 1.0, so there is underlying support for the means to asynchronously flush buffers to disk/network as described in the example above.

API Proposal

public abstract class TextWriter : MarshalByRefObject, IAsyncDisposable, IDisposable
{
    public virtual System.Threading.Tasks.Task FlushAsync (CancellationToken cancellationToken);
}

API Usage

async Task PrintReportAsync(TextWriter writer, CancellationToken cancellationToken = default)
{
    await writer.WriteLineAsync("Some data".AsMemory(), cancellationToken);
    await writer.FlushAsync(cancellationToken);
}

Alternative Designs

Alternatively, ValueTask could be used, but based on the other APIs that do not return a value, it would seem that Task is preferred here.

public abstract class TextWriter : MarshalByRefObject, IAsyncDisposable, IDisposable
{
    public virtual System.Threading.Tasks.ValueTask FlushAsync (CancellationToken cancellationToken);
}

Risks

No response

References

• Add CancellationToken to StreamReader.Read* methods #20824
• Add CancellationToken to TextReader.ReadXAsync #61898

[ghost]

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

Issue Details

---

Background and motivation

Some TextWriter implementations such as StreamWriter serve to encode data in a particular format and then write that data to an underlying data stream. The underlying data stream could easily be a file stream or network stream, where it is desired to be able to cancel any pending operation upon either an upstream cancellation (e.g. termination of the HTTP request that initiated such as data transfer) or user request (e.g. user clicks Cancel button).

Some implementations also buffer data before reaching the underlying stream, and without a call to Flush (or AutoFlush = true), do not flush those buffers to the underlying stream. So it is sometimes necessary in these instances to call Flush to ensure that the TextWriter implementation has flushed its buffers to the underlying stream, even if it is not necessary to flush the underlying stream. Typical implementations of Flush however will typically flush their own buffers and then call the Flush method of the underlying stream.

Calling FlushAsync on an underlying data stream can often result in an asynchronous delay while the data is written to disk or sent over the network. However, the method does not provide any means to cancel the underlying write/flush operation.

With the merging of #61898, both TextReader and TextWriter supports cancellation tokens for each of their methods (in some form) except this one.

Note that the Stream.FlushAsync method has an overload with a cancellation token since .NET Standard 1.0, so there is underlying support for the means to asynchronously flush buffers to disk/network as described in the example above.

References:

• Add CancellationToken to StreamReader.Read* methods #20824
• Add CancellationToken to TextReader.ReadXAsync #61898

API Proposal

public abstract class TextWriter : MarshalByRefObject, IAsyncDisposable, IDisposable
{
    public virtual System.Threading.Tasks.Task FlushAsync (CancellationToken cancellationToken);
}

API Usage

async Task PrintReportAsync(TextWriter writer, CancellationToken cancellationToken = default)
{
    await writer.WriteLineAsync("Some data".AsMemory(), cancellationToken);
    await writer.FlushAsync(cancellationToken);
}

Alternative Designs

Alternatively, ValueTask could be used, but based on the other APIs that do not return a value, it would seem that Task is preferred here.

public abstract class TextWriter : MarshalByRefObject, IAsyncDisposable, IDisposable
{
    public virtual System.Threading.Tasks.ValueTask FlushAsync (CancellationToken cancellationToken);
}

Risks

No response

Author:	Shane32
Assignees:	-
Labels:	api-suggestion, area-System.IO, untriaged
Milestone:	-

[terrajobst]

Video

• Looks good as proposed

namespace System.IO;

public partial class TextWriter
{
    // Existing:
    // public virtual Task FlushAsync();
    public virtual Task FlushAsync(CancellationToken cancellationToken);
}