[API Proposal]: PipeStream.WaitForPipeDrainAsync(CancellationToken cancellationToken)

[Symbai]

Background and motivation

Currently WaitForPipe() is blocking the thread. Adding an async version with support for timeout let us better handle situations where the client cannot or has not read all remaining bytes within an expected duration. I.e. network failure or delay or client has been shut down etc.

API Proposal

namespace System.IO.Pipes

public abstract class PipeStream : Stream
{
    public Task WaitForPipeDrainAsync(CancellationToken cancellationToken);
}

API Usage

var ct = new CancellationTokenSource(3_000).Token;
try
{
    await NamedPipe.WaitForPipeDrainAsync(ct)
}
catch (OperationCanceledException e)
{
    //Retry or do something else
}

Alternative Designs

No response

Risks

No response

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

Currently WaitForPipe() is blocking the thread. Adding an async version with support for timeout let us better handle situations where the client cannot or has not read all remaining bytes within an expected duration. I.e. network failure or delay or client has been shut down etc.

API Proposal

namespace System.IO.Pipes

public abstract class PipeStream : Stream
{
    public Task WaitForPipeDrainAsync(CancellationToken cancellationToken);
}

API Usage

var ct = new CancellationTokenSource(3_000).Token;
try
{
    await NamedPipe.WaitForPipeDrainAsync(ct)
}
catch (OperationCanceledException e)
{
    //Retry or do something else
}



### Alternative Designs

_No response_

### Risks

_No response_

<table>
  <tr>
    <th align="left">Author:</th>
    <td>Symbai</td>
  </tr>
  <tr>
    <th align="left">Assignees:</th>
    <td>-</td>
  </tr>
  <tr>
    <th align="left">Labels:</th>
    <td>

`api-suggestion`, `area-System.IO`

</td>
  </tr>
  <tr>
    <th align="left">Milestone:</th>
    <td>-</td>
  </tr>
</table>
</details>

[jozkee]

WaitForPipeDrain uses FlushFileBuffers, do you know which WinAPI should be used for this async version?

[Symbai]

No, I have no idea how it works internally. But since we also have async file IO APIs like WriteAllBytesAsync and there is no async windows API for that too, I would assume WaitForPipeDrainAsync does not really require an async windows API as well.

[stephentoub]

since we also have async file IO APIs like WriteAllBytesAsync and there is no async windows API for that too

There is. WriteAllBytesAsync is implemented on top of WriteFile, which supports overlapped I/O.

[Symbai]

I think I've seen existing .NET APIs which provide an async version which itself is just using a Task and wait for its result. How does FlushAsync work, is there an async windows API?

[stephentoub]

I think I've seen existing .NET APIs which provide an async version which itself is just using a Task and wait for its result.

Only when we're forced to due to e.g. deriving from a base type that provides a virtual/abstract we need to override.

How does FlushAsync work, is there an async windows API?

FileStream.FlushASync? It takes the buffer stored in the FileStream and writes it out to the file essentially using WriteAsync.