Hide get sequence until we deal with use-after-free

sdk/core/Azure.Core/api/Azure.Core.net461.cs

@@ -724,7 +724,6 @@ public SequenceWriter(int bufferSize = 4096) { }
         public void Advance(int bytesWritten) { }
         public void Dispose() { }
         public System.Memory<byte> GetMemory(int sizeHint = 0) { throw null; }
-        public System.Buffers.ReadOnlySequence<byte> GetReadOnlySequence() { throw null; }
         public System.Span<byte> GetSpan(int sizeHint = 0) { throw null; }
         public bool TryComputeLength(out long length) { throw null; }
         public void WriteTo(System.IO.Stream stream, System.Threading.CancellationToken cancellation) { }

sdk/core/Azure.Core/api/Azure.Core.net5.0.cs

@@ -724,7 +724,6 @@ public SequenceWriter(int bufferSize = 4096) { }
         public void Advance(int bytesWritten) { }
         public void Dispose() { }
         public System.Memory<byte> GetMemory(int sizeHint = 0) { throw null; }
-        public System.Buffers.ReadOnlySequence<byte> GetReadOnlySequence() { throw null; }
         public System.Span<byte> GetSpan(int sizeHint = 0) { throw null; }
         public bool TryComputeLength(out long length) { throw null; }
         public void WriteTo(System.IO.Stream stream, System.Threading.CancellationToken cancellation) { }

sdk/core/Azure.Core/api/Azure.Core.net6.0.cs

@@ -724,7 +724,6 @@ public SequenceWriter(int bufferSize = 4096) { }
         public void Advance(int bytesWritten) { }
         public void Dispose() { }
         public System.Memory<byte> GetMemory(int sizeHint = 0) { throw null; }
-        public System.Buffers.ReadOnlySequence<byte> GetReadOnlySequence() { throw null; }
         public System.Span<byte> GetSpan(int sizeHint = 0) { throw null; }
         public bool TryComputeLength(out long length) { throw null; }
         public void WriteTo(System.IO.Stream stream, System.Threading.CancellationToken cancellation) { }

sdk/core/Azure.Core/api/Azure.Core.netcoreapp2.1.cs

@@ -724,7 +724,6 @@ public SequenceWriter(int bufferSize = 4096) { }
         public void Advance(int bytesWritten) { }
         public void Dispose() { }
         public System.Memory<byte> GetMemory(int sizeHint = 0) { throw null; }
-        public System.Buffers.ReadOnlySequence<byte> GetReadOnlySequence() { throw null; }
         public System.Span<byte> GetSpan(int sizeHint = 0) { throw null; }
         public bool TryComputeLength(out long length) { throw null; }
         public void WriteTo(System.IO.Stream stream, System.Threading.CancellationToken cancellation) { }

sdk/core/Azure.Core/api/Azure.Core.netstandard2.0.cs

@@ -724,7 +724,6 @@ public SequenceWriter(int bufferSize = 4096) { }
         public void Advance(int bytesWritten) { }
         public void Dispose() { }
         public System.Memory<byte> GetMemory(int sizeHint = 0) { throw null; }
-        public System.Buffers.ReadOnlySequence<byte> GetReadOnlySequence() { throw null; }
         public System.Span<byte> GetSpan(int sizeHint = 0) { throw null; }
         public bool TryComputeLength(out long length) { throw null; }
         public void WriteTo(System.IO.Stream stream, System.Threading.CancellationToken cancellation) { }

sdk/core/Azure.Core/src/SequenceWriter.cs

@@ -10,7 +10,7 @@
 namespace Azure.Core
 {
     /// <summary>
-    /// .
+    /// A buffer writer which writes large sequences of data into smaller shared buffers.
     /// </summary>
     public sealed class SequenceWriter : IBufferWriter<byte>, IDisposable
     {
@@ -25,19 +25,20 @@ private struct Buffer
         private int _bufferSize;
 
         /// <summary>
-        /// .
+        /// Initializes a new instance of <see cref="SequenceWriter"/>.
         /// </summary>
-        /// <param name="bufferSize"></param>
+        /// <param name="bufferSize">The max size of each buffer segment.</param>
         public SequenceWriter(int bufferSize = 4096)
         {
             _bufferSize = bufferSize;
             _buffers = Array.Empty<Buffer>();
         }
 
         /// <summary>
-        /// .
+        /// Notifies the <see cref="SequenceWriter"/> that bytes bytes were written to the output <see cref="Span{T}"/> or <see cref="Memory{T}"/>.
+        /// You must request a new buffer after calling <see cref="Advance(int)"/> to continue writing more data; you cannot write to a previously acquired buffer.
         /// </summary>
-        /// <param name="bytesWritten"></param>
+        /// <param name="bytesWritten">The number of bytes written to the <see cref="Span{T}"/> or <see cref="Memory{T}"/>.</param>
         /// <exception cref="ArgumentOutOfRangeException"></exception>
         public void Advance(int bytesWritten)
         {
@@ -50,19 +51,21 @@ public void Advance(int bytesWritten)
         }
 
         /// <summary>
-        /// .
+        /// Returns a <see cref="Memory{T}"/> to write to that is at least the requested size, as specified by the <paramref name="sizeHint"/> parameter.
         /// </summary>
-        /// <param name="sizeHint"></param>
-        /// <returns></returns>
+        /// <param name="sizeHint">The minimum length of the returned <see cref="Memory{T}"/>. If less than 256, a buffer of size 256 will be returned.</param>
+        /// <returns>A memory buffer of at least <paramref name="sizeHint"/> bytes. If <paramref name="sizeHint"/> is less than 256, a buffer of size 256 will be returned.</returns>
         public Memory<byte> GetMemory(int sizeHint = 0)
         {
             if (sizeHint < 256)
                 sizeHint = 256;
 
+            int sizeToRent = sizeHint > _bufferSize ? sizeHint : _bufferSize;
+
             if (_buffers.Length == 0)
             {
                 _buffers = new Buffer[1];
-                _buffers[0].Array = ArrayPool<byte>.Shared.Rent(_bufferSize);
+                _buffers[0].Array = ArrayPool<byte>.Shared.Rent(sizeToRent);
                 _count = 1;
             }
 
@@ -72,7 +75,7 @@ public Memory<byte> GetMemory(int sizeHint = 0)
                 return free;
 
             // else allocate a new buffer:
-            var newArray = ArrayPool<byte>.Shared.Rent(_bufferSize);
+            var newArray = ArrayPool<byte>.Shared.Rent(sizeToRent);
 
             // add buffer to _buffers
             if (_buffers.Length == _count)
@@ -89,10 +92,10 @@ public Memory<byte> GetMemory(int sizeHint = 0)
         }
 
         /// <summary>
-        /// .
+        /// Returns a <see cref="Span{T}"/> to write to that is at least the requested size, as specified by the <paramref name="sizeHint"/> parameter.
         /// </summary>
-        /// <param name="sizeHint"></param>
-        /// <returns></returns>
+        /// <param name="sizeHint">The minimum length of the returned <see cref="Span{T}"/>. If less than 256, a buffer of size 256 will be returned.</param>
+        /// <returns>A buffer of at least <paramref name="sizeHint"/> bytes. If <paramref name="sizeHint"/> is less than 256, a buffer of size 256 will be returned.</returns>
         public Span<byte> GetSpan(int sizeHint = 0)
         {
             Memory<byte> memory = GetMemory(sizeHint);
@@ -115,11 +118,7 @@ public void Dispose()
             _count = 0;
         }
 
-        /// <summary>
-        /// Compute the length of the data written to the SequenceWriter.
-        /// </summary>
-        /// <param name="length"> The length of the buffer returned. </param>
-        /// <returns> A bool indicating whether or not the length was able to be calculated. </returns>
+        /// <inheritdoc cref="RequestContent.TryComputeLength(out long)"/>
         public bool TryComputeLength(out long length)
         {
             length = 0;
@@ -131,11 +130,7 @@ public bool TryComputeLength(out long length)
             return true;
         }
 
-        /// <summary>
-        /// .
-        /// </summary>
-        /// <param name="stream"></param>
-        /// <param name="cancellation"></param>
+        /// <inheritdoc cref="RequestContent.WriteTo(Stream, CancellationToken)"/>
         public void WriteTo(Stream stream, CancellationToken cancellation)
         {
             for (int i = 0; i < _count; i++)
@@ -145,12 +140,7 @@ public void WriteTo(Stream stream, CancellationToken cancellation)
             }
         }
 
-        /// <summary>
-        /// .
-        /// </summary>
-        /// <param name="stream"></param>
-        /// <param name="cancellation"></param>
-        /// <returns></returns>
+        /// <inheritdoc cref="RequestContent.WriteToAsync(Stream, CancellationToken)"/>
         public async Task WriteToAsync(Stream stream, CancellationToken cancellation)
         {
             for (int i = 0; i < _count; i++)
@@ -175,10 +165,9 @@ public void Add(byte[] array, int length)
         }
 
         /// <summary>
-        /// .
+        /// Gets a <see cref="ReadOnlySequence{T}"/> representing the data written to the SequenceWriter.
         /// </summary>
-        /// <returns></returns>
-        public ReadOnlySequence<byte> GetReadOnlySequence()
+        internal ReadOnlySequence<byte> GetReadOnlySequence()
         {
             if (_count == 0)
                 return ReadOnlySequence<byte>.Empty;

sdk/core/Azure.Core/tests/SequenceWriterTests.cs

@@ -0,0 +1,73 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using System;
+using System.Buffers;
+using NUnit.Framework;
+
+namespace Azure.Core.Tests
+{
+    internal class SequenceWriterTests
+    {
+        [Test]
+        public void ValidateEmptyBuffer()
+        {
+            SequenceWriter writer = new SequenceWriter();
+            Assert.IsTrue(writer.TryComputeLength(out var length));
+            Assert.AreEqual(0, length);
+            Assert.AreEqual(ReadOnlySequence<byte>.Empty, writer.GetReadOnlySequence());
+        }
+
+        [Test]
+        public void ValidateSingleBuffer()
+        {
+            SequenceWriter writer = new SequenceWriter(512);
+            WriteMemory(writer, 400, 0xFF);
+
+            var sequence = writer.GetReadOnlySequence();
+
+            Assert.AreEqual(400, sequence.Length);
+            Assert.AreEqual(0xFF, sequence.First.Span[0]);
+            Assert.AreEqual(0xFF, sequence.Slice(399).First.Span[0]);
+        }
+
+        [Test]
+        public void ValidateMultiBuffer()
+        {
+            SequenceWriter writer = new SequenceWriter(512);
+            WriteMemory(writer, 400, 0xFF);
+            WriteMemory(writer, 400, 0xFF);
+
+            var sequence = writer.GetReadOnlySequence();
+
+            Assert.AreEqual(800, sequence.Length);
+            Assert.AreEqual(0xFF, sequence.First.Span[0]);
+            Assert.AreEqual(0xFF, sequence.Slice(399).First.Span[0]);
+            Assert.AreEqual(0xFF, sequence.Slice(400).First.Span[0]);
+            Assert.AreEqual(0xFF, sequence.Slice(799).First.Span[0]);
+        }
+
+        [Test]
+        public void CanWriteMoreThanBufferSize()
+        {
+            SequenceWriter writer = new SequenceWriter(512);
+            WriteMemory(writer, 513, 0xFF);
+            WriteMemory(writer, 256, 0xFE);
+
+            Assert.IsTrue(writer.TryComputeLength(out var length));
+            Assert.AreEqual(769, length);
+
+            var sequence = writer.GetReadOnlySequence();
+            Assert.AreEqual(769, sequence.Length);
+            Assert.AreEqual(0xFF, sequence.First.Span[0]);
+            Assert.AreEqual(0xFE, sequence.Slice(514).First.Span[0]);
+        }
+
+        private static void WriteMemory(SequenceWriter writer, int size, byte data)
+        {
+            var memory = writer.GetMemory(size);
+            memory.Span.Slice(0, size).Fill(data);
+            writer.Advance(size);
+        }
+    }
+}