CA1844

docs/fundamentals/code-analysis/quality-rules/ca1844.md

@@ -0,0 +1,52 @@
+---
+title: "CA1844: Provide memory-based overrides of async methods when subclassing 'Stream' (code analysis)"
+description: "Learn about code analysis rule CA1844: Provide memory-based overrides of async methods when subclassing 'Stream'"
+ms.date: 05/18/2021
+ms.topic: reference
+f1_keywords:
+- CA1844
+- ProvideStreamMemoryBasedAsyncOverrides
+helpviewer_keywords:
+- ProvideStreamMemoryBasedAsyncOverrides
+- CA1844
+author: NewellClark
+dev_langs:
+- CSharp
+- VB
+---
+# CA1844: Provide memory-based overrides of async methods when subclassing 'Stream'
+
+| | Value |
+|-|-|
+| **Rule ID** |CA1844|
+| **Category** |[Performance](performance-warnings.md)|
+| **Fix is breaking or non-breaking** |Non-breaking|
+
+## Cause
+
+A type derived from <xref:System.IO.Stream> overrides <xref:System.IO.Stream.ReadAsync(System.Byte[],System.Int32,System.Int32,System.Threading.CancellationToken)> but does not override <xref:System.IO.Stream.ReadAsync(System.Memory{System.Byte},System.Threading.CancellationToken)>. Or, a type derived from <xref:System.IO.Stream> overrides  <xref:System.IO.Stream.WriteAsync(System.Byte[],System.Int32,System.Int32,System.Threading.CancellationToken)> but does not override <xref:System.IO.Stream.WriteAsync(System.ReadOnlyMemory{System.Byte},System.Threading.CancellationToken)>.
+
+## Rule description
+
+The memory-based `ReadAsync` and `WriteAsync` methods were added to improve performance, which they accomplish in multiple ways:
+
+- They return `ValueTask` and `ValueTask<int>` instead of `Task` and `Task<int>`, respectively.
+- They allow any type of buffer to be passed in without having to perform an extra copy to an array.
+
+In order to realize these performance benefits, types that derive from <xref:System.IO.Stream> must provide their own memory-based implementation. Otherwise, the default implementation will be forced to copy the memory into an array in order to call the array-based implementation, resulting in reduced performance. When the caller passes in a <xref:System.Memory%601> or <xref:System.ReadOnlyMemory%601> instance that's not backed by an array, performance is affected more.
+
+## How to fix violations
+
+The easiest way to fix violations is to rewrite your array-based implementation as a memory-based implementation, and then implement the array-based methods in terms of the memory-based methods.
+
+## When to suppress warnings
+
+It's safe to suppress a warning from this rule if any of the following situations apply:
+
+- The performance hit is not a concern.
+- You know that your `Stream` subclass will only ever use the array-based methods.
+- Your `Stream` subclass has dependencies that don't support memory-based buffers.
+
+## See also
+
+- [Performance rules](performance-warnings.md)

docs/fundamentals/code-analysis/quality-rules/index.md

@@ -130,6 +130,7 @@ The following table lists code quality analysis rules.
 > | [CA1837: Use `Environment.ProcessId` instead of `Process.GetCurrentProcess().Id`](ca1837.md) | `Environment.ProcessId` is simpler and faster than `Process.GetCurrentProcess().Id`. |
 > | [CA1838: Avoid `StringBuilder` parameters for P/Invokes](ca1838.md) | Marshaling of 'StringBuilder' always creates a native buffer copy, resulting in multiple allocations for one marshaling operation. |
 > | [CA1841: Prefer Dictionary Contains methods](ca1841.md) | Calling `Contains` on the `Keys` or `Values` collection may often be more expensive than calling `ContainsKey` or `ContainsValue` on the dictionary itself. |
+> | [CA1844: Provide memory-based overrides of async methods when subclassing 'Stream'](ca1844.md) | To improve performance, override the memory-based async methods when subclassing 'Stream'. Then implement the array-based methods in terms of the memory-based methods. |
 > | [CA1845: Use span-based 'string.Concat'](ca1845.md) | It is more efficient to use `AsSpan` and `string.Concat`, instead of `Substring` and a concatenation operator. |
 > | [CA2000: Dispose objects before losing scope](ca2000.md) | Because an exceptional event might occur that will prevent the finalizer of an object from running, the object should be explicitly disposed before all references to it are out of scope. |
 > |[CA2002: Do not lock on objects with weak identity](ca2002.md) |An object is said to have a weak identity when it can be directly accessed across application domain boundaries. A thread that tries to acquire a lock on an object that has a weak identity can be blocked by a second thread in a different application domain that has a lock on the same object. |

docs/fundamentals/code-analysis/quality-rules/performance-warnings.md

@@ -50,4 +50,5 @@ Performance rules support high-performance libraries and applications.
 | [CA1837: Use `Environment.ProcessId` instead of `Process.GetCurrentProcess().Id`](ca1837.md) | `Environment.ProcessId` is simpler and faster than `Process.GetCurrentProcess().Id`. |
 | [CA1838: Avoid `StringBuilder` parameters for P/Invokes](ca1838.md) | Marshaling of `StringBuilder` always creates a native buffer copy, resulting in multiple allocations for one marshaling operation. |
 | [CA1841: Prefer Dictionary Contains methods](ca1841.md) | Calling `Contains` on the `Keys` or `Values` collection may often be more expensive than calling `ContainsKey` or `ContainsValue` on the dictionary itself. |
+| [CA1844: Provide memory-based overrides of async methods when subclassing 'Stream'](ca1844.md) | To improve performance, override the memory-based async methods when subclassing 'Stream'. Then implement the array-based methods in terms of the memory-based methods. |
 | [CA1845: Use span-based 'string.Concat'](ca1845.md) | It is more efficient to use `AsSpan` and `string.Concat`, instead of `Substring` and a concatenation operator. |

docs/fundamentals/toc.yml

@@ -876,6 +876,8 @@ items:
             href: code-analysis/quality-rules/ca1838.md
           - name: CA1841
             href: code-analysis/quality-rules/ca1841.md
+          - name: CA1844
+            href: code-analysis/quality-rules/ca1844.md
           - name: CA1845
             href: code-analysis/quality-rules/ca1845.md
         - name: SingleFile rules