Documentation for Memory<T>, IMemoryOwner<T> #548

rpetrusha · 2018-09-24T17:12:29Z

Documentation for Memory<T>, IMemoryOwner<T>

ReadOnlyMemory<T> will be documented after review comments are incorporated into Memory<T>.

@stephentoub @ahsonkhan

Related to dotnet/samples#444

Fixes dotnet/docs#4400

ahsonkhan · 2018-09-24T18:34:53Z

cc @GrabYourPitchforks

ahsonkhan · 2018-09-24T18:37:05Z

xml/System.Buffers/IMemoryOwner`1.xml

+    <remarks>
+      <format type="text/markdown"><![CDATA[  
+
+The `IMemoryOwner<T>` interface is used to define the owner responsible for the lifetime management of a <xref:System.Memory%601> buffer. An instance of the `IMemoryOwner<T>` interface is returned by the <xref:System.Buffers.ArrayPool%601.Rent%2A?displayProperty=nameWithType> and <xef:System.Buffers.MemoryPool%601.Rent%2A?displayProperty=nameWithType> methods. 


We don't return IMemoryOwner from ArrayPool.Rent.

But MemoryPool.Rent does, just to clarify.

also fix from xef to xref

ahsonkhan · 2018-09-24T18:38:05Z

xml/System.Buffers/IMemoryOwner`1.xml

-        <summary>To be added.</summary>
-        <value>To be added.</value>
+        <summary>Gets the memory belonging to this owner.</summary>
+        <value>The memory belonging to this owner.</value>


The remarks field still states "To be added."

@ahsonkhan If any field has "to be added." then it will not be displayed in the published article. It's a "magic" value.

ahsonkhan · 2018-09-24T18:41:02Z

xml/System/Memory`1.xml

+       <remarks>
+          <format type="text/markdown"><![CDATA[  
+
+If `array` is `null`, this constructor returns a `null` <xref:System.Memory%601> object.


Memory<T> is a struct and can't be null. So stating that it returns a null object could cause confusion. It returns the default struct.

ahsonkhan · 2018-09-24T18:43:05Z

xml/System/Memory`1.xml

+      ]]></format>
+        </remarks>
+        <exception cref="T:System.ArrayTypeMismatchException">
+          <paramref name="T" /> is a reference type, and <paramref name="array" /> is not an array of type <paramref name="T" />.</exception>


Would it be useful to mention that this could occur due to co-variant arrays?
https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/covariance-contravariance/

ahsonkhan · 2018-09-24T18:48:19Z

xml/System/Memory`1.xml

+        <param name="other">The object to compare with the current instance.</param>
+        <summary>Determines whether the specified <see cref="T:System.Memory`1" /> object is equal to the current object.</summary>
+        <returns><see langword="true" /> if the current instance and <paramref name="other" /> are equal; otherwise, <see langword="false" />. </returns>
+        <remarks>


We should probably add a remark to clarify that this is purely reference equality and we are not comparing the elements of Memory<T> for equality.

ahsonkhan · 2018-09-24T18:50:50Z

xml/System/Memory`1.xml

+        <param name="start">The index at which to begin the slice.</param>
+        <param name="length">The number of elements to include in the slice.</param>
+        <summary>Forms a slice out of the current memory starting at a specified index for a specified length.</summary>
+        <returns>An object that <paramref name="length" /> elements from the current instance starting at <paramref name="start" />. </returns>


Sentence is awkward to read

Summary really explains it best. Return should just be shortened to something like "Memory object contain X elements from the current instance.

ahsonkhan · 2018-09-24T18:55:18Z

xml/System/Span`1.xml

+
+## Span\<T> and slices
+
+`Span\<T>` includes two overloads of the <xref:System.Span%601.Slice%2A> method that forms a slice out of the current span that starts at a specified index. This makes it possible to treat the data in a `Span\<T>` as a set of logical chunks that can be processed as needed by portions of a data processing pipeline with minimal performance impact. For example, since modern server protocols are often text-based, manipulation of strings and substrings is particularly important. In the <xref:System.String> class, the major method for extracting substrings is <xref:System.String.Substring%2A>. For data pipelines that rely on extensive string manipulation, it use offers some performance penalties, since it:


For data pipelines that rely on extensive string manipulation, it use offers some performance penalties, since it

... its use offers...

ahsonkhan · 2018-09-24T18:55:37Z

xml/System/Memory`1.xml

-        <returns>To be added.</returns>
+        <param name="array">The array to convert.</param>
+        <summary>Defines an implicit conversion of an array to a <see cref="T:System.Memory`1" /> object.</summary>
+        <returns>The converted object.</returns>


To be added remarks here and elsewhere

That's fine @ahsonkhan. It's the default value and is not rendered on docs.

stephentoub · 2018-09-24T19:50:51Z

xml/System/Memory`1.xml

+
+## Remarks  
+
+Like <xref:System.Span%601>, `Memory<T>` represents a contiguous region of memory. Unlike <xref:System.Span%601>, however, `Memory<T>` is not a [ref struct](~/doocs/csharp/reference-semantics-with-value-types?view=netcore-2.1.md#ref-struct-type). This means that `Memory<T>` can be backed by:


This means that...

That difference, struct vs ref struct, really just impacts whether or not it can be stored on the heap, which in turn impacts whether it can be used as a field in a class, whether it can used across await and yield boundaries, etc.

stephentoub · 2018-09-24T19:55:33Z

xml/System/Memory`1.xml

+- A string (a sequence of characters).
+- A <xref:System.Runtime.InteropServices.SafeHandle>.
+
+`Memory<T>` cannot be backed by transient unmanaged memory, such as memory available by using [stackalloc](~/docs/csharp/language-reference/keywords/stackalloc.md).


This isn't really true. With IMemoryPool<T>, a Memory<T> can be created that's backed pretty much any contiguous memory, regardless of where it came from: if you can get a pointer to it, you can create a Memory<T> for it... it just requires some more work to do.

stephentoub · 2018-09-24T19:56:13Z

xml/System/Memory`1.xml

+
+`Memory<T>` cannot be backed by transient unmanaged memory, such as memory available by using [stackalloc](~/docs/csharp/language-reference/keywords/stackalloc.md).
+
+Because the memory allocated to the `Memory<T>` structure is placed on the managed heap, it does not have the same restrictions as a <xref:System.Span%601> instance. In particular:


This isn't quite right. Memory<T> is just a struct... it could live on the managed heap (as a field on a class), but it could also, for example, be on the stack.

Isn't this restriction (on span) related to the fact that it's a ref struct? So memory not being a ref struct, doesn't have those restrictions?

stephentoub · 2018-09-24T19:57:58Z

xml/System/Memory`1.xml

+       <remarks>
+          <format type="text/markdown"><![CDATA[  
+
+If `array` is `null`, this constructor returns a `null` <xref:System.Memory%601> object.


As per Ahson's comments earlier, you don't get back null... you get back default(Memory<T>), i.e. basically a zero'd-out Memory<T>.

stephentoub · 2018-09-24T20:00:40Z

xml/System/Memory`1.xml

+
+- An array.
+- A string (a sequence of characters).
+- A <xref:System.Runtime.InteropServices.SafeHandle>.


SafeHandle?

stephentoub · 2018-09-24T20:02:00Z

xml/System.Buffers/IMemoryOwner`1.xml

+
+   ]]></format>
+
+    </remarks>


I assume we'll have a subsequent PR that adds the relevant safety rules related to IMemoryOwner<T>, e.g. it shouldn't be disposed of while a reference to its memory is handed out, which generally means it shouldn't have a finalizer, etc.?

do you have a place where these safety rules are discussed @stephentoub?

Thraka

Some minor fixes. One bad link though

Thraka · 2018-11-06T18:50:01Z

xml/System/Memory`1.xml

+
+## Remarks  
+
+Like <xref:System.Span%601>, `Memory<T>` represents a contiguous region of memory. Unlike <xref:System.Span%601>, however, `Memory<T>` is not a [ref struct](~/doocs/csharp/reference-semantics-with-value-types?view=netcore-2.1.md#ref-struct-type). This means that `Memory<T>` can be placed on the managed heap, whereas <xref:System.Span%601> cannot. As a result, the `Memory<T>` structure does not have the same restrictions as a <xref:System.Span%601> instance. In particular:


it says /doocs instead of /docs

Thraka · 2018-11-06T18:59:16Z

xml/System/Memory`1.xml

-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <summary>Creates a handle for the <see cref="T:System.Memory`1" /> object.</summary>
+        <returns>a handle for the <see cref="T:System.Memory`1" /> object.</returns>


capitol A at the start

rpetrusha · 2018-11-07T16:08:36Z

Closing and reopening to begin new build.

mairaw requested review from Thraka, stephentoub and ahsonkhan September 24, 2018 17:43

rpetrusha changed the title ~~Documentation for Memory\<T>, IMemoryOwner\<T>~~ Documentation for Memory<T>, IMemoryOwner<T> Sep 24, 2018

ahsonkhan reviewed Sep 24, 2018

View reviewed changes

stephentoub reviewed Sep 24, 2018

View reviewed changes

mairaw mentioned this pull request Oct 22, 2018

Does this make alwas make copy? dotnet/docs#7961

Closed

mairaw requested a review from GrabYourPitchforks October 24, 2018 19:44

Ron Petrusha added 9 commits November 5, 2018 17:20

Initial checkin

d811f4d

second check-in

a2c3e8d

Documented Memory<T>

2dd64d8

Additional commit

c1182cd

Incremental commit

3c24025

Added some detail

f781ac0

Fixed malformed XML

f42a0eb

Fixed more malformed XML

98428c9

more malformed xml

0ac6065

Incorporated reveiw comments

7ab0f22

rpetrusha force-pushed the memory branch from a4bd1c7 to 7ab0f22 Compare November 6, 2018 01:32

Minor changes

d78b873

Thraka suggested changes Nov 6, 2018

View reviewed changes

Addressed feedback, fixed invalid XML

6a0b966

Thraka approved these changes Nov 6, 2018

View reviewed changes

rpetrusha mentioned this pull request Nov 6, 2018

Span examples dotnet/samples#444

Merged

rpetrusha added the 🚧 Hold for related PR Indicates a PR can only be merged when other related PRs are merged (see comments for links) label Nov 6, 2018

Added code, fixed bad xrefs

0293869

rpetrusha closed this Nov 7, 2018

rpetrusha reopened this Nov 7, 2018

Ron Petrusha added 2 commits November 7, 2018 09:54

Fixed broken links

29b588a

Corrected final bad xref

0a04cee

rpetrusha merged commit d162f97 into dotnet:master Nov 8, 2018

rpetrusha deleted the memory branch November 8, 2018 01:10

This was referenced Nov 8, 2018

MemoryPool<T> has a poor description dotnet/docs#8931

Closed

Memory<T>.Pin doc needs to be filled out dotnet/docs#8925

Closed

rpetrusha mentioned this pull request Dec 17, 2018

Document remaining Memory<T>-related APIs #1411

Closed

14 tasks

mairaw removed the 🚧 Hold for related PR Indicates a PR can only be merged when other related PRs are merged (see comments for links) label Jan 23, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation for Memory<T>, IMemoryOwner<T> #548

Documentation for Memory<T>, IMemoryOwner<T> #548

rpetrusha commented Sep 24, 2018 •

edited

Loading

ahsonkhan commented Sep 24, 2018

ahsonkhan Sep 24, 2018

stephentoub Sep 24, 2018 •

edited

Loading

mairaw Oct 24, 2018

ahsonkhan Sep 24, 2018

Thraka Sep 26, 2018

ahsonkhan Sep 24, 2018

ahsonkhan Sep 24, 2018

ahsonkhan Sep 24, 2018

ahsonkhan Sep 24, 2018

Thraka Oct 9, 2018

ahsonkhan Sep 24, 2018

ahsonkhan Sep 24, 2018

mairaw Sep 24, 2018

stephentoub Sep 24, 2018

stephentoub Sep 24, 2018

stephentoub Sep 24, 2018

Thraka Oct 9, 2018

stephentoub Sep 24, 2018

stephentoub Sep 24, 2018

stephentoub Sep 24, 2018

mairaw Oct 24, 2018

Thraka left a comment

Thraka Nov 6, 2018

Thraka Nov 6, 2018

rpetrusha commented Nov 7, 2018


		## Span\<T> and slices

		`Span\<T>` includes two overloads of the <xref:System.Span%601.Slice%2A> method that forms a slice out of the current span that starts at a specified index. This makes it possible to treat the data in a `Span\<T>` as a set of logical chunks that can be processed as needed by portions of a data processing pipeline with minimal performance impact. For example, since modern server protocols are often text-based, manipulation of strings and substrings is particularly important. In the <xref:System.String> class, the major method for extracting substrings is <xref:System.String.Substring%2A>. For data pipelines that rely on extensive string manipulation, it use offers some performance penalties, since it:


		## Remarks

		Like <xref:System.Span%601>, `Memory<T>` represents a contiguous region of memory. Unlike <xref:System.Span%601>, however, `Memory<T>` is not a [ref struct](~/doocs/csharp/reference-semantics-with-value-types?view=netcore-2.1.md#ref-struct-type). This means that `Memory<T>` can be backed by:


		`Memory<T>` cannot be backed by transient unmanaged memory, such as memory available by using [stackalloc](~/docs/csharp/language-reference/keywords/stackalloc.md).

		Because the memory allocated to the `Memory<T>` structure is placed on the managed heap, it does not have the same restrictions as a <xref:System.Span%601> instance. In particular:

Documentation for Memory<T>, IMemoryOwner<T> #548

Documentation for Memory<T>, IMemoryOwner<T> #548

Conversation

rpetrusha commented Sep 24, 2018 • edited Loading