Prepare 2.2.1 release. Update version numbers. Regenerate documentati…

…on. (#245)

Co-authored-by: Ben Watson <bewatson@microsoft.com>

CHANGES.md

@@ -1,3 +1,12 @@
+# Version 2.2.1
+
+API change:
+* There are now overloads that take a type `long` parameter for requestedSize.
+
+Bug Fix:
+* `ToString` will no longer throw an exception if the stream is disposed.
+
+
 # Version 2.2.0
 
 API changes:

docs/Microsoft.IO/RecyclableMemoryStreamManager.md

@@ -37,11 +37,11 @@ public sealed class RecyclableMemoryStreamManager
 | event [StreamDisposed](RecyclableMemoryStreamManager/StreamDisposed.md) | Triggered when a stream is disposed. |
 | event [StreamDoubleDisposed](RecyclableMemoryStreamManager/StreamDoubleDisposed.md) | Triggered when a stream is disposed of twice (an error). |
 | event [StreamFinalized](RecyclableMemoryStreamManager/StreamFinalized.md) | Triggered when a stream is finalized. |
-| event [StreamLength](RecyclableMemoryStreamManager/StreamLength.md) | Triggered when a stream is finalized. |
+| event [StreamLength](RecyclableMemoryStreamManager/StreamLength.md) | Triggered when a stream is disposed to report the stream's length. |
 | event [StreamOverCapacity](RecyclableMemoryStreamManager/StreamOverCapacity.md) | Triggered when a stream is requested to expand beyond the maximum length specified by the responsible RecyclableMemoryStreamManager. |
 | event [UsageReport](RecyclableMemoryStreamManager/UsageReport.md) | Periodically triggered to report usage statistics. |
 | [GetStream](RecyclableMemoryStreamManager/GetStream.md)() | Retrieve a new `MemoryStream` object with no tag and a default initial capacity. |
-| [GetStream](RecyclableMemoryStreamManager/GetStream.md)(…) | Retrieve a new `MemoryStream` object with no tag and a default initial capacity. (16 methods) |
+| [GetStream](RecyclableMemoryStreamManager/GetStream.md)(…) | Retrieve a new `MemoryStream` object with no tag and a default initial capacity. (19 methods) |
 | const [DefaultBlockSize](RecyclableMemoryStreamManager/DefaultBlockSize.md) | Default block size, in bytes. |
 | const [DefaultLargeBufferMultiple](RecyclableMemoryStreamManager/DefaultLargeBufferMultiple.md) | Default large buffer multiple, in bytes. |
 | const [DefaultMaximumBufferSize](RecyclableMemoryStreamManager/DefaultMaximumBufferSize.md) | Default maximum buffer size, in bytes. |

docs/Microsoft.IO/RecyclableMemoryStreamManager/GetStream.md

@@ -1,4 +1,4 @@
-# RecyclableMemoryStreamManager.GetStream method (1 of 17)
+# RecyclableMemoryStreamManager.GetStream method (1 of 20)
 
 Retrieve a new `MemoryStream` object with no tag and a default initial capacity.
 
@@ -17,7 +17,7 @@ A `MemoryStream`.
 
 ---
 
-# RecyclableMemoryStreamManager.GetStream method (2 of 17)
+# RecyclableMemoryStreamManager.GetStream method (2 of 20)
 
 Retrieve a new `MemoryStream` object with the contents copied from the provided buffer. The provided buffer is not wrapped or used after construction.
 
@@ -44,7 +44,7 @@ The new stream's position is set to the beginning of the stream when returned.
 
 ---
 
-# RecyclableMemoryStreamManager.GetStream method (3 of 17)
+# RecyclableMemoryStreamManager.GetStream method (3 of 20)
 
 Retrieve a new `MemoryStream` object with no tag and a default initial capacity.
 
@@ -67,7 +67,7 @@ A `MemoryStream`.
 
 ---
 
-# RecyclableMemoryStreamManager.GetStream method (4 of 17)
+# RecyclableMemoryStreamManager.GetStream method (4 of 20)
 
 Retrieve a new `MemoryStream` object with the contents copied from the provided buffer. The provided buffer is not wrapped or used after construction.
 
@@ -95,7 +95,7 @@ The new stream's position is set to the beginning of the stream when returned.
 
 ---
 
-# RecyclableMemoryStreamManager.GetStream method (5 of 17)
+# RecyclableMemoryStreamManager.GetStream method (5 of 20)
 
 Retrieve a new `MemoryStream` object with the contents copied from the provided buffer. The provided buffer is not wrapped or used after construction.
 
@@ -122,7 +122,7 @@ The new stream's position is set to the beginning of the stream when returned.
 
 ---
 
-# RecyclableMemoryStreamManager.GetStream method (6 of 17)
+# RecyclableMemoryStreamManager.GetStream method (6 of 20)
 
 Retrieve a new `MemoryStream` object with the given tag and a default initial capacity.
 
@@ -145,7 +145,7 @@ A `MemoryStream`.
 
 ---
 
-# RecyclableMemoryStreamManager.GetStream method (7 of 17)
+# RecyclableMemoryStreamManager.GetStream method (7 of 20)
 
 Retrieve a new `MemoryStream` object with the given tag and a default initial capacity.
 
@@ -169,7 +169,7 @@ A `MemoryStream`.
 
 ---
 
-# RecyclableMemoryStreamManager.GetStream method (8 of 17)
+# RecyclableMemoryStreamManager.GetStream method (8 of 20)
 
 Retrieve a new `MemoryStream` object with the given tag and at least the given capacity.
 
@@ -193,7 +193,7 @@ A `MemoryStream`.
 
 ---
 
-# RecyclableMemoryStreamManager.GetStream method (9 of 17)
+# RecyclableMemoryStreamManager.GetStream method (9 of 20)
 
 Retrieve a new `MemoryStream` object with the given tag and with contents copied from the provided buffer. The provided buffer is not wrapped or used after construction.
 
@@ -222,7 +222,7 @@ The new stream's position is set to the beginning of the stream when returned.
 
 ---
 
-# RecyclableMemoryStreamManager.GetStream method (10 of 17)
+# RecyclableMemoryStreamManager.GetStream method (10 of 20)
 
 Retrieve a new `MemoryStream` object with the given tag and with contents copied from the provided buffer. The provided buffer is not wrapped or used after construction.
 
@@ -250,7 +250,7 @@ The new stream's position is set to the beginning of the stream when returned.
 
 ---
 
-# RecyclableMemoryStreamManager.GetStream method (11 of 17)
+# RecyclableMemoryStreamManager.GetStream method (11 of 20)
 
 Retrieve a new `MemoryStream` object with the given tag and at least the given capacity.
 
@@ -275,7 +275,32 @@ A `MemoryStream`.
 
 ---
 
-# RecyclableMemoryStreamManager.GetStream method (12 of 17)
+# RecyclableMemoryStreamManager.GetStream method (12 of 20)
+
+Retrieve a new `MemoryStream` object with the given tag and at least the given capacity.
+
+```csharp
+public MemoryStream GetStream(Guid id, string tag, long requiredSize)
+```
+
+| parameter | description |
+| --- | --- |
+| id | A unique identifier which can be used to trace usages of the stream. |
+| tag | A tag which can be used to track the source of the stream. |
+| requiredSize | The minimum desired capacity for the stream. |
+
+## Return Value
+
+A `MemoryStream`.
+
+## See Also
+
+* class [RecyclableMemoryStreamManager](../RecyclableMemoryStreamManager.md)
+* namespace [Microsoft.IO](../../Microsoft.IO.RecyclableMemoryStream.md)
+
+---
+
+# RecyclableMemoryStreamManager.GetStream method (13 of 20)
 
 Retrieve a new `MemoryStream` object with the given tag and with contents copied from the provided buffer. The provided buffer is not wrapped or used after construction.
 
@@ -305,7 +330,7 @@ The new stream's position is set to the beginning of the stream when returned.
 
 ---
 
-# RecyclableMemoryStreamManager.GetStream method (13 of 17)
+# RecyclableMemoryStreamManager.GetStream method (14 of 20)
 
 Retrieve a new `MemoryStream` object with the given tag and with contents copied from the provided buffer. The provided buffer is not wrapped or used after construction.
 
@@ -334,7 +359,7 @@ The new stream's position is set to the beginning of the stream when returned.
 
 ---
 
-# RecyclableMemoryStreamManager.GetStream method (14 of 17)
+# RecyclableMemoryStreamManager.GetStream method (15 of 20)
 
 Retrieve a new `MemoryStream` object with the given tag and at least the given capacity, possibly using a single contiguous underlying buffer.
 
@@ -363,7 +388,36 @@ Retrieving a MemoryStream which provides a single contiguous buffer can be usefu
 
 ---
 
-# RecyclableMemoryStreamManager.GetStream method (15 of 17)
+# RecyclableMemoryStreamManager.GetStream method (16 of 20)
+
+Retrieve a new `MemoryStream` object with the given tag and at least the given capacity, possibly using a single contiguous underlying buffer.
+
+```csharp
+public MemoryStream GetStream(string tag, long requiredSize, bool asContiguousBuffer)
+```
+
+| parameter | description |
+| --- | --- |
+| tag | A tag which can be used to track the source of the stream. |
+| requiredSize | The minimum desired capacity for the stream. |
+| asContiguousBuffer | Whether to attempt to use a single contiguous buffer. |
+
+## Return Value
+
+A `MemoryStream`.
+
+## Remarks
+
+Retrieving a MemoryStream which provides a single contiguous buffer can be useful in situations where the initial size is known and it is desirable to avoid copying data between the smaller underlying buffers to a single large one. This is most helpful when you know that you will always call [`GetBuffer`](../RecyclableMemoryStream/GetBuffer.md) on the underlying stream.
+
+## See Also
+
+* class [RecyclableMemoryStreamManager](../RecyclableMemoryStreamManager.md)
+* namespace [Microsoft.IO](../../Microsoft.IO.RecyclableMemoryStream.md)
+
+---
+
+# RecyclableMemoryStreamManager.GetStream method (17 of 20)
 
 Retrieve a new `MemoryStream` object with the given tag and at least the given capacity, possibly using a single contiguous underlying buffer.
 
@@ -393,7 +447,37 @@ Retrieving a `MemoryStream` which provides a single contiguous buffer can be use
 
 ---
 
-# RecyclableMemoryStreamManager.GetStream method (16 of 17)
+# RecyclableMemoryStreamManager.GetStream method (18 of 20)
+
+Retrieve a new `MemoryStream` object with the given tag and at least the given capacity, possibly using a single contiguous underlying buffer.
+
+```csharp
+public MemoryStream GetStream(Guid id, string tag, long requiredSize, bool asContiguousBuffer)
+```
+
+| parameter | description |
+| --- | --- |
+| id | A unique identifier which can be used to trace usages of the stream. |
+| tag | A tag which can be used to track the source of the stream. |
+| requiredSize | The minimum desired capacity for the stream. |
+| asContiguousBuffer | Whether to attempt to use a single contiguous buffer. |
+
+## Return Value
+
+A `MemoryStream`.
+
+## Remarks
+
+Retrieving a `MemoryStream` which provides a single contiguous buffer can be useful in situations where the initial size is known and it is desirable to avoid copying data between the smaller underlying buffers to a single large one. This is most helpful when you know that you will always call [`GetBuffer`](../RecyclableMemoryStream/GetBuffer.md) on the underlying stream.
+
+## See Also
+
+* class [RecyclableMemoryStreamManager](../RecyclableMemoryStreamManager.md)
+* namespace [Microsoft.IO](../../Microsoft.IO.RecyclableMemoryStream.md)
+
+---
+
+# RecyclableMemoryStreamManager.GetStream method (19 of 20)
 
 Retrieve a new `MemoryStream` object with the given tag and with contents copied from the provided buffer. The provided buffer is not wrapped or used after construction.
 
@@ -423,7 +507,7 @@ The new stream's position is set to the beginning of the stream when returned.
 
 ---
 
-# RecyclableMemoryStreamManager.GetStream method (17 of 17)
+# RecyclableMemoryStreamManager.GetStream method (20 of 20)
 
 Retrieve a new `MemoryStream` object with the given tag and with contents copied from the provided buffer. The provided buffer is not wrapped or used after construction.
 

docs/Microsoft.IO/RecyclableMemoryStreamManager/StreamLength.md

@@ -1,6 +1,6 @@
 # RecyclableMemoryStreamManager.StreamLength event
 
-Triggered when a stream is finalized.
+Triggered when a stream is disposed to report the stream's length.
 
 ```csharp
 public event EventHandler<StreamLengthEventArgs> StreamLength;

generatedocs.cmd

@@ -1,2 +1,8 @@
-# uses xmldocmd from https://github.com/ejball/XmlDocMarkdown
-xmldocmd .\src\bin\Release\netstandard2.1\Microsoft.IO.RecyclableMemoryStream.dll .\docs --obsolete --clean
+@ECHO OFF
+ECHO ===========================================================
+ECHO Using xmldocmd from https://github.com/ejball/XmlDocMarkdown
+ECHO ===========================================================
+
+xmldocmd .\src\bin\Release\netstandard2.1\Microsoft.IO.RecyclableMemoryStream.dll .\docs --obsolete --clean
+
+ECHO Done.

src/Microsoft.IO.RecyclableMemoryStream.csproj

@@ -6,7 +6,7 @@
     <DocumentationFile>bin\$(Configuration)\$(TargetFramework)\Microsoft.IO.RecyclableMemoryStream.xml</DocumentationFile>
     <!-- NuGet properties -->
     <PackageId>Microsoft.IO.RecyclableMemoryStream</PackageId>
-    <PackageVersion>2.2.0</PackageVersion>
+    <PackageVersion>2.2.1</PackageVersion>
     <Title>Microsoft.IO.RecyclableMemoryStream</Title>
     <Authors>Microsoft</Authors>
     <Description>A pooled MemoryStream allocator to decrease GC load and improve performance on highly scalable systems.</Description>

src/Properties/AssemblyInfo.cs

@@ -34,8 +34,8 @@
 // You can specify all the values or you can default the Build and Revision Numbers 
 // by using the '*' as shown below:
 // [assembly: AssemblyVersion("1.0.*")]
-[assembly: AssemblyVersion("2.2.0.0")]
-[assembly: AssemblyFileVersion("2.2.0.0")]
+[assembly: AssemblyVersion("2.2.1.0")]
+[assembly: AssemblyFileVersion("2.2.1.0")]
 
 [assembly: CLSCompliant(true)]