Support appending foreign buffers to pipe without copy

[tmds]

Moved from dotnet/corefxlab#2031

Foreign buffers are buffers not allocated with the Pipe MemoryPool.

Use-cases (by @Drawaes @mgravell @ReubenBond)

• Send the same data to multiple Pipes
• Pass existing data that is not related to pipelines
• Embed existing data (e.g. add header)

With the current API, these buffers are copied into buffers owned by the Pipe MemoryPool:

Challenges:

• The buffer usage needs to be tracked in order to know when it can be re-used.
• some Transports (e.g. RIO) may not be capable of sending foreign buffers. They should detect this and copy the data in an appropriate buffer.

CC @davidfowl

[Drawaes]

One factor to consider is that the use case I have most of the time will not be a "foreign" buffer it will be from the same pool just a different pipe. So it should be fine in the RIO case.

Also we managed to sneak in some changes to pipelines that will allow a buffer to identify it's pool in the final API reviews before lockdown.

[BrennanConroy]

From #32894:

This API would allow a user to insert their own buffer into a PipeWriter's stream.

This allows a PipeWriter to be truly zero-copy for such a scenario, while currently they must copy their buffer into the PipeWriter's internal buffer. An example might be a block of pre-serialized data that a user might reuse throughout a stream's lifetime. The transport implementation could then take the resulting sequence of the PipeWriter's own buffers and the user's buffers and perform a gathered write to the socket.

class PipeWriter
{
    // Allocate a reusable block that is guaranteed to be zero-copy if passed to AppendBuffer().
    public virtual IMemoryOwner<byte> GetReusableMemory(int length);

    // If the buffer is compatible with the pipe writer's needs, use the buffer directly. Otherwise, do an implicit GetSpan()+Copy()+Advance().
    // ValueTask completes once the buffer is no longer in use by the PipeWriter.
    // Unlike WriteAsync, does not flush.
    public virtual ValueTask AppendBufferAsync(ReadOnlyMemory<byte> buffer);
}

[dotnet-policy-service]

Due to lack of recent activity, this issue has been marked as a candidate for backlog cleanup. It will be closed if no further activity occurs within 14 more days. Any new comment (by anyone, not necessarily the author) will undo this process.

This process is part of our issue cleanup automation.

[dotnet-policy-service]

This issue will now be closed since it had been marked no-recent-activity but received no further activity in the past 14 days. It is still possible to reopen or comment on the issue, but please note that the issue will be locked if it remains inactive for another 30 days.