Create usage guidelines for lifetime management of System.Memory<T>

[joshfree]

Memory, and OwnedMemory are new types shipping in .NET Core 2.1. Memory/OwnedMemory need "rules of the road" usage guidance in order to write code that doesn't cause use-after-free bugs.

https://github.com/dotnet/corefx/issues/23863

https://github.com/dotnet/corefxlab/blob/master/docs/specs/span.md

https://github.com/dotnet/corefxlab/blob/master/docs/specs/memory.md

(The below is edited by @GrabYourPitchforks.)

The document at https://gist.github.com/GrabYourPitchforks/4c3e1935fd4d9fa2831dbfcab35dffc6 demonstrates how to think about Memory<T>. It goes over issues related to lifetime and gives a set of guidelines for developers who want to accept Memory<T> instances in their API surface. Read this document first.

The document at https://gist.github.com/GrabYourPitchforks/8efb15abbd90bc5b128f64981766e834 talks about MemoryPool<T> and related types, including how to write custom pools. It also goes over how to change the implementation of Memory<T> to get it to point to new categories of contiguous buffers, such as unmanaged memory. It covers more advanced scenarios.

[mairaw]

@GrabYourPitchforks @KrzysztofCwalina you both are assigned to this issue. Does that mean you're going to help with the docs? 😄

[joshfree]

@mairaw they've already written the fairly thorough usage guidelines gist above. What's the next step?

[cartermp]

The next step here would be to turn these gists into docs under (the poorly named) /docs/dotnet/standard folder. Place in the table of contents isn't quite as important, since organic search is where we'd want these to be picked up. It could either be a sub-TOC, or there could be separate articles. I'll leave that preference up to @mairaw.

[mairaw]

@rpetrusha is currently working on the API docs for for Memory and perhaps could start on this on the next few sprints. It's just that there's a lot going on so we haven't been able to get started on this one yet @joshfree.