docs(mtconnect): state AsStream's buffer aliasing and lifetime contract

2026-08-17 05:31:28 -04:00
parent 248d998a79
commit 1edfc263ec
1 changed files with 10 additions and 1 deletions
@@ -241,7 +241,16 @@ internal static class MTConnectStreamsParser
    /// <summary>
    ///     Views the (already trimmed) bytes as a stream without copying them where the memory is
    ///     array-backed — which it always is on the <c>/sample</c> path, whose framer hands over the
-    ///     part's own <c>byte[]</c>.
+    ///     part's own <c>byte[]</c>. That branch <b>aliases</b> the caller's array; only the
+    ///     non-array-backed fallback copies (via <c>ToArray</c>).
+    ///     <para>
+    ///         Ownership, so a caller can reason about the aliased buffer: nothing on this path pools
+    ///         or rents it (the framer allocates each <c>byte[]</c> fresh), and parsing is fully
+    ///         synchronous, so the buffer need only stay valid and unmutated for the duration of the
+    ///         <c>Parse</c> call. The returned <see cref="MTConnectStreamsResult"/> holds no reference
+    ///         into it — <see cref="XmlReader"/> materialises its own strings — so the caller may
+    ///         reuse or discard the buffer as soon as <c>Parse</c> returns.
+    ///     </para>
    /// </summary>
    private static MemoryStream AsStream(ReadOnlyMemory<byte> xml) =>
        MemoryMarshal.TryGetArray(xml, out ArraySegment<byte> segment) && segment.Array is not null