Merge branch 'master' of /home/vihofer/consolidation/artifacts/corefx

docs/libraries/README.md

@@ -0,0 +1,72 @@
+Documents Index
+===============
+
+Intro to .NET Core
+==================
+
+.NET Core is a self-contained .NET runtime and framework that implements ECMA 335. It can be (and has been) ported to multiple architectures and platforms. It support a variety of installation options, having no specific deployment requirements itself.
+
+Learn about .NET Core
+====================
+
+- [Official .NET Core Docs](https://docs.microsoft.com/dotnet/core)
+
+Get .NET Core
+=============
+
+- [Get .NET Core SDK](https://www.microsoft.com/net/core)
+
+Architecture Docs
+=================
+
+- [.NET Core Globalization Invariant Mode](architecture/globalization-invariant-mode.md)
+- [Cross-Platform Cryptography](architecture/cross-platform-cryptography.md)
+
+Project Docs
+============
+
+- [Developer Guide](project-docs/developer-guide.md)
+- [Performance Testing](project-docs/performance-tests.md)
+- [Contributing to CoreFX](project-docs/contributing.md)
+- [Contributing to .NET Core](https://github.com/dotnet/coreclr/blob/master/Documentation/project-docs/contributing.md)
+- [Contributing Workflow](https://github.com/dotnet/coreclr/blob/master/Documentation/project-docs/contributing-workflow.md)
+- [Issue Guide](project-docs/issue-guide.md)
+- [Branching Guide](project-docs/branching-guide.md)
+- [API Review Process](project-docs/api-review-process.md)
+- [Strong Name Signing](project-docs/strong-name-signing.md)
+- [Public Signing](project-docs/public-signing.md)
+- [Repo Organization](project-docs/repo-organization.md)
+- [Project NuGet Dependencies](https://github.com/dotnet/buildtools/blob/master/Documentation/project-nuget-dependencies.md)
+- [Profiling CoreFX](https://github.com/dotnet/performance/blob/master/docs/profiling-workflow-corefx.md)
+
+Coding Guidelines
+=================
+
+- [C# coding style](coding-guidelines/coding-style.md)
+- [Framework Design Guidelines](coding-guidelines/framework-design-guidelines-digest.md)
+- [Cross-Platform Guidelines](coding-guidelines/cross-platform-guidelines.md)
+- [Performance Guidelines](coding-guidelines/performance-guidelines.md)
+- [Interop Guidelines](coding-guidelines/interop-guidelines.md)
+- [Breaking Changes](coding-guidelines/breaking-changes.md)
+- [Breaking Change Definitions](coding-guidelines/breaking-change-definitions.md)
+- [Breaking Change Rules](coding-guidelines/breaking-change-rules.md)
+- [Project Guidelines](coding-guidelines/project-guidelines.md)
+- [Adding APIs Guidelines](coding-guidelines/adding-api-guidelines.md)
+- [Legal Native calls](building/pinvoke-checker.md)
+
+Building from Source
+====================
+
+- [Building CoreFX on FreeBSD, Linux and OS X](building/unix-instructions.md)
+- [Code Coverage](building/code-coverage.md)
+- [Cross Building](building/cross-building.md)
+- [Package and Assembly File Versioning](building/versioning.md)
+
+Other Information
+=================
+
+- [CoreCLR Repo documentation](https://github.com/dotnet/coreclr/tree/master/Documentation)
+- [Porting to .NET Core](project-docs/support-dotnet-core-instructions.md)
+- [.NET Standards (Ecma)](https://github.com/dotnet/coreclr/blob/master/Documentation/project-docs/dotnet-standards.md)
+- [MSDN Entry for the CLR](http://msdn.microsoft.com/library/8bs2ecf4.aspx)
+- [Wikipedia Entry for the CLR](http://en.wikipedia.org/wiki/Common_Language_Runtime)

docs/libraries/api-guidelines/README.md

@@ -0,0 +1,13 @@
+# API Design Guidelines
+
+The guidelines in this folder represent work in progress API design guidelines.
+The official guidelines can be found in the [documentation][docs] and as an
+actual [book].
+
+## Process
+
+To submit new proposals for design guidelines, simply create a PR adding or
+modifying an existing file.
+
+[docs]: https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/
+[book]: https://amazon.com/dp/0321545613

docs/libraries/api-guidelines/System.Memory.md

@@ -0,0 +1,54 @@
+# System.Memory Design Guidelines
+
+`System.Memory` is a collection of types and features that make working with
+buffers and raw memory more efficient while remaining type safe. The feature
+specs can be found here:
+
+* [`Span<T>`](https://github.com/dotnet/corefxlab/blob/master/docs/specs/span.md)
+* [`Memory<T>`](https://github.com/dotnet/corefxlab/blob/master/docs/specs/memory.md)
+
+## Overview
+
+* `ReadOnlySpan<T>` is effectively the universal receiver, in that `T[]`, `T*`,
+  `Memory<T>`, `ReadOnlyMemory<T>`, `Span<T>`, `ArraySegment<T>` can all be
+  converted to it. So if you can declare your API to accept a `ReadOnlySpan<T>`
+  and behave efficiently, that's best, as any of these inputs can be used with
+  your method.
+* Similarly for `Span<T>`, if you need write access in the implementation.
+* It allows building safe public APIs that can operate on unmanaged memory
+  without forcing all consumers to use pointers (and thus becoming unsafe). The
+  implementation can still extract a raw pointer, therefore getting equivalent
+  performance if necessary.
+* It's generally best for a synchronous method to accept `Span<T>` or
+  `ReadOnlySpan<T>`. However, since `ReadOnlySpan<T>`/`Span<T>` are stack-only
+  [1], this may be too limiting for the implementation. In particular, if the
+  implementation needs to be able to store the argument for later usage, such as
+  with an asynchronous method or an iterator, `ReadOnlySpan<T>`/`Span<T>` is
+  inappropriate. `ReadOnlyMemory<T>`/`Memory<T>` should be used in such
+  situations.
+
+
+[1] *stack-only* isn't the best way to put it. Strictly speaking, these types
+    are called `ref`-like types. These types must be structs, cannot be fields
+    in classes, cannot be boxed, and cannot be used to instantiate generic
+    types. Value types containing fields of `ref`-like types must themselves be
+    `ref`-like types.
+
+## Guidance
+
+* **DO NOT** use pointers for methods operating on buffers. Instead, use
+  appropriate type from below. In performance critical code where bounds
+  checking is unacceptable, the method's implementation can still pin the span
+  and get the raw pointer if necessary. The key is that you don't spread the
+  pointer through the public API.
+    - Synchronous, read-only access needed: `ReadOnlySpan<T>`
+    - Synchronous, writable access needed: `Span<T>`
+    - Asynchronous, read-only access needed: `ReadOnlyMemory<T>`
+    - Asynchronous, writable access needed: `Memory<T>`
+* **CONSIDER** using `stackalloc` with `Span<T>` when you need small temporary
+  storage but you need to avoid allocations and associated life-time management.
+* **AVOID** providing overloads for both `ReadOnlySpan<T>` and `Span<T>` as `Span<T>`
+  can be implicitly converted to `ReadOnlySpan<T>`.
+* **AVOID** providing overloads for both `ReadOnlySpan<T>`/`Span<T>` as well as
+  pointers and arrays as those can be implicitly converted to
+  `ReadOnlySpan<T>`/`Span<T>`.