Fix Memory<T> usage example

docs/standard/memory-and-spans/memory-t-usage-guidelines.md

@@ -1,20 +1,20 @@
 ---
 title: "Memory<T> and Span<T> usage guidelines"
-description: This article describes Memory<T> and Span<T>, which are buffers of structured data in .NET Core that can be used in pipelines.
-ms.date: 02/05/2021
+description: This article describes Memory<T> and Span<T>, which are buffers of structured data in .NET that can be used in pipelines.
+ms.date: 04/19/2023
 helpviewer_keywords: 
   - "Memory&lt;T&gt; and Span&lt;T&gt; best practices"
   - "using Memory&lt;T&gt; and Span&lt;T&gt;"
 ---
 # Memory\<T> and Span\<T> usage guidelines
 
-.NET Core includes a number of types that represent an arbitrary contiguous region of memory. .NET Core 2.0 introduced <xref:System.Span%601> and <xref:System.ReadOnlySpan%601>, which are lightweight memory buffers that wrap references to managed or unmanaged memory. Because these types can only be stored on the stack, they are unsuitable for a number of scenarios, including asynchronous method calls. .NET Core 2.1 adds a number of additional types, including <xref:System.Memory%601>, <xref:System.ReadOnlyMemory%601>, <xref:System.Buffers.IMemoryOwner%601>, and <xref:System.Buffers.MemoryPool%601>. Like <xref:System.Span%601>, <xref:System.Memory%601> and its related types can be backed by both managed and unmanaged memory. Unlike <xref:System.Span%601>, <xref:System.Memory%601> can be stored on the managed heap.
+.NET includes a number of types that represent an arbitrary contiguous region of memory. <xref:System.Span%601> and <xref:System.ReadOnlySpan%601> are lightweight memory buffers that wrap references to managed or unmanaged memory. Because these types can only be stored on the stack, they're unsuitable for scenarios such as asynchronous method calls. To address this problem, .NET 2.1 added some additional types, including <xref:System.Memory%601>, <xref:System.ReadOnlyMemory%601>, <xref:System.Buffers.IMemoryOwner%601>, and <xref:System.Buffers.MemoryPool%601>. Like <xref:System.Span%601>, <xref:System.Memory%601> and its related types can be backed by both managed and unmanaged memory. Unlike <xref:System.Span%601>, <xref:System.Memory%601> can be stored on the managed heap.
 
-Both <xref:System.Span%601> and <xref:System.Memory%601> are wrappers over buffers of structured data that can be used in pipelines. That is, they are designed so that some or all of the data can be efficiently passed to components in the pipeline, which can process them and optionally modify the buffer. Because <xref:System.Memory%601> and its related types can be accessed by multiple components or by multiple threads, it's important that developers follow some standard usage guidelines to produce robust code.
+Both <xref:System.Span%601> and <xref:System.Memory%601> are wrappers over buffers of structured data that can be used in pipelines. That is, they're designed so that some or all of the data can be efficiently passed to components in the pipeline, which can process them and optionally modify the buffer. Because <xref:System.Memory%601> and its related types can be accessed by multiple components or by multiple threads, it's important to follow some standard usage guidelines to produce robust code.
 
 ## Owners, consumers, and lifetime management
 
-Since buffers can be passed around between APIs, and since buffers can sometimes be accessed from multiple threads, it's important to consider lifetime management. There are three core concepts:
+Buffers can be passed around between APIs and can sometimes be accessed from multiple threads, so be aware of how a buffer's lifetime is managed. There are three core concepts:
 
 - **Ownership**. The owner of a buffer instance is responsible for lifetime management, including destroying the buffer when it's no longer in use. All buffers have a single owner. Generally the owner is the component that created the buffer or that received the buffer from a factory. Ownership can also be transferred; **Component-A** can relinquish control of the buffer to **Component-B**, at which point **Component-A** may no longer use the buffer, and **Component-B** becomes responsible for destroying the buffer when it's no longer in use.
 
@@ -61,7 +61,7 @@ The `WriteInt32ToBuffer` method has a lease on (can consume) the buffer between
 
 ## Memory\<T> and the owner/consumer model
 
-As the [Owners, consumers, and lifetime management](#owners-consumers-and-lifetime-management) section notes, a buffer always has an owner. .NET Core supports two ownership models:
+As the [Owners, consumers, and lifetime management](#owners-consumers-and-lifetime-management) section notes, a buffer always has an owner. .NET supports two ownership models:
 
 - A model that supports single ownership. A buffer has a single owner for its entire lifetime.
 
@@ -71,17 +71,17 @@ You use the <xref:System.Buffers.IMemoryOwner%601?displayProperty=nameWithType>
 
 [!code-csharp[ownership](~/samples/snippets/standard/buffers/memory-t/owner/owner.cs)]
 
-We can also write this example with the [`using`](../../csharp/language-reference/statements/using.md):
+We can also write this example with the [`using` statement](../../csharp/language-reference/statements/using.md):
 
 [!code-csharp[ownership-using](~/samples/snippets/standard/buffers/memory-t/owner-using/owner-using.cs)]
 
 In this code:
 
 - The `Main` method holds the reference to the <xref:System.Buffers.IMemoryOwner%601> instance, so the `Main` method is the owner of the buffer.
 
-- The `WriteInt32ToBuffer` and `DisplayBufferToConsole` methods accept <xref:System.Memory%601> as a public API. Therefore, they are consumers of the buffer. And they only consume it one at a time.
+- The `WriteInt32ToBuffer` and `DisplayBufferToConsole` methods accept <xref:System.Memory%601> as a public API. Therefore, they are consumers of the buffer. These methods consume the buffer one at a time.
 
-Although the `WriteInt32ToBuffer` method is intended to write a value to the buffer, the `DisplayBufferToConsole` method isn't. To reflect this, it could have accepted an argument of type <xref:System.ReadOnlyMemory%601>. For more information on <xref:System.ReadOnlyMemory%601>, see [Rule #2: Use ReadOnlySpan\<T> or ReadOnlyMemory\<T> if the buffer should be read-only](#rule-2).
+Although the `WriteInt32ToBuffer` method is intended to write a value to the buffer, the `DisplayBufferToConsole` method isn't intended to. To reflect this, it could have accepted an argument of type <xref:System.ReadOnlyMemory%601>. For more information on <xref:System.ReadOnlyMemory%601>, see [Rule #2: Use ReadOnlySpan\<T> or ReadOnlyMemory\<T> if the buffer should be read-only](#rule-2).
 
 ### "Ownerless" Memory\<T> instances
 
@@ -97,15 +97,15 @@ The method that initially creates the <xref:System.Memory%601> instance is the i
 
 ## Usage guidelines
 
-Because a memory block is owned but is intended to be passed to multiple components, some of which may operate upon a particular memory block simultaneously, it is important to establish guidelines for using both <xref:System.Memory%601> and <xref:System.Span%601>.  Guidelines are necessary because:
+Because a memory block is owned but is intended to be passed to multiple components, some of which may operate upon a particular memory block simultaneously, it's important to establish guidelines for using both <xref:System.Memory%601> and <xref:System.Span%601>. Guidelines are necessary because it's possible for a component to:
 
-- It is possible for a component to retain a reference to a memory block after its owner has released it.
+- Retain a reference to a memory block after its owner has released it.
 
-- It is possible for a component to operate on a buffer at the same time that another component is operating on it, in the process corrupting the data in the buffer.
+- Operate on a buffer at the same time that another component is operating on it, in the process corrupting the data in the buffer.
 
-- While the stack-allocated nature of <xref:System.Span%601> optimizes performance and makes <xref:System.Span%601> the preferred type for operating on a memory block, it also subjects <xref:System.Span%601> to some major restrictions. It is important to know when to use a <xref:System.Span%601> and when to use <xref:System.Memory%601>.
+- While the stack-allocated nature of <xref:System.Span%601> optimizes performance and makes <xref:System.Span%601> the preferred type for operating on a memory block, it also subjects <xref:System.Span%601> to some major restrictions. It's important to know when to use a <xref:System.Span%601> and when to use <xref:System.Memory%601>.
 
-The following are our recommendations for successfully using <xref:System.Memory%601> and its related types. Guidance that applies to <xref:System.Memory%601> and <xref:System.Span%601> also applies to <xref:System.ReadOnlyMemory%601> and <xref:System.ReadOnlySpan%601> unless we explicitly note otherwise.
+The following are our recommendations for successfully using <xref:System.Memory%601> and its related types. Guidance that applies to <xref:System.Memory%601> and <xref:System.Span%601> also applies to <xref:System.ReadOnlyMemory%601> and <xref:System.ReadOnlySpan%601> unless noted otherwise.
 
 **Rule #1: For a synchronous API, use Span\<T> instead of Memory\<T> as a parameter if possible.**
 
@@ -171,7 +171,7 @@ There are several ways to resolve this:
 
 This is just the async variant of Rule #3. The `Log` method from the earlier example can be written as follows to comply with this rule:
 
-[!code-csharp[task-returning-async](~/samples/snippets/standard/buffers/memory-t/void-returning-async/void-returning-async.cs#1)]
+[!code-csharp[task-returning-async](~/samples/snippets/standard/buffers/memory-t/task-returning-async/task-returning-async.cs#1)]
 
 Here, "terminal state" means that the task transitions to a completed, faulted, or canceled state. In other words, "terminal state" means "anything that would cause await to throw or to continue execution."
 

samples/snippets/standard/buffers/memory-t/task-returning-async/project.csproj

@@ -0,0 +1,9 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net7.0</TargetFramework>
+    <RootNamespace>task_returning_async</RootNamespace>
+  </PropertyGroup>
+
+</Project>

samples/snippets/standard/buffers/memory-t/task-returning-async/task-returning-async.cs

@@ -0,0 +1,48 @@
+using System;
+using System.Buffers;
+using System.IO;
+using System.Threading.Tasks;
+
+public class Example
+{
+    // <Snippet1>
+    // An acceptable implementation.
+    static Task Log(ReadOnlyMemory<char> message)
+    {
+        // Run in the background so that we don't block the main thread while performing IO.
+        return Task.Run(() =>
+        {
+            StreamWriter sw = File.AppendText(@".\input-numbers.dat");
+            sw.WriteLine(message);
+            sw.Flush();
+        });
+    }
+    // </Snippet1>
+
+    // user code
+    public static void Main()
+    {
+        using (var owner = MemoryPool<char>.Shared.Rent())
+        {
+            var memory = owner.Memory;
+            var span = memory.Span;
+            while (true)
+            {
+                int value = Int32.Parse(Console.ReadLine());
+                if (value < 0)
+                    return;
+
+                int numCharsWritten = ToBuffer(value, span);
+                Log(memory.Slice(0, numCharsWritten));
+            }
+        }
+    }
+
+    private static int ToBuffer(int value, Span<char> span)
+    {
+        string strValue = value.ToString();
+        int length = strValue.Length;
+        strValue.AsSpan().CopyTo(span.Slice(0, length));
+        return length;
+    }
+}

samples/snippets/standard/buffers/memory-t/task-returning/task-returning.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net6.0</TargetFramework>
+    <TargetFramework>net7.0</TargetFramework>
     <RootNamespace>void_returning</RootNamespace>
   </PropertyGroup>