From 437971376995184f5afe191319bf224a19513389 Mon Sep 17 00:00:00 2001 From: Saisang Cai Date: Fri, 2 Feb 2024 14:22:09 +0800 Subject: [PATCH 1/4] Update low-level-struct-improvements.md --- proposals/csharp-11.0/low-level-struct-improvements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/csharp-11.0/low-level-struct-improvements.md b/proposals/csharp-11.0/low-level-struct-improvements.md index 1bbc968659..5f2fae0103 100644 --- a/proposals/csharp-11.0/low-level-struct-improvements.md +++ b/proposals/csharp-11.0/low-level-struct-improvements.md @@ -6,7 +6,7 @@ Low Level Struct Improvements ## Summary This proposal is an aggregation of several different proposals for `struct` performance improvements: `ref` fields and the ability to override lifetime defaults. The goal being a design which takes into account the various proposals to create a single overarching feature set for low level `struct` improvements. -> Note: Previous versions of this spec used the terms "ref-safe-to-escape" and "safe-to-escape", which were introduced in the [Span safety](https://github.com/dotnet/csharplang/blob/main/proposals/csharp-7.2/span-safety.md) feature specification. The [ECMA standard committee](https://www.ecma-international.org/task-groups/tc49-tg2/) changed the names to ["ref-safe-context"](https://learn.microsoft.com/dotnet/csharp/language-reference/language-specification/variables#972-ref-safe-contexts) and ["safe-context"](https://learn.microsoft.com/dotnet/csharp/language-reference/language-specification/structs#16412-safe-context-constraint), respectively. The values of the safe context have been refined to use "declaration-block", "function-member", and "caller-context" consistently. The speclets had used different phrasing for these terms, and also used "safe-to-return" as a synonym for "caller-context". This speclet has been updated to use the terms in the C# 7.3 standard. +> Note: Previous versions of this spec used the terms "ref-safe-to-escape" and "safe-to-escape", which were introduced in the [Span safety](https://github.com/dotnet/csharplang/blob/main/proposals/csharp-7.2/span-safety.md) feature specification. The [ECMA standard committee](https://www.ecma-international.org/task-groups/tc49-tg2/) changed the names to ["ref-safe-context"](/dotnet/csharp/language-reference/language-specification/variables#972-ref-safe-contexts) and ["safe-context"](/dotnet/csharp/language-reference/language-specification/structs#16412-safe-context-constraint), respectively. The values of the safe context have been refined to use "declaration-block", "function-member", and "caller-context" consistently. The speclets had used different phrasing for these terms, and also used "safe-to-return" as a synonym for "caller-context". This speclet has been updated to use the terms in the C# 7.3 standard. ## Motivation Earlier versions of C# added a number of low level performance features to the language: `ref` returns, `ref struct`, function pointers, etc. ... These enabled .NET developers to write highly performant code while continuing to leverage the C# language rules for type and memory safety. It also allowed the creation of fundamental performance types in the .NET libraries like `Span`. From 321de9f683fd004bfafa8d9d095b4e8f7725bddc Mon Sep 17 00:00:00 2001 From: Saisang Cai Date: Fri, 2 Feb 2024 14:24:11 +0800 Subject: [PATCH 2/4] Update collection-expressions.md --- proposals/csharp-12.0/collection-expressions.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/csharp-12.0/collection-expressions.md b/proposals/csharp-12.0/collection-expressions.md index 60c3cc88cd..c30b29b1ac 100644 --- a/proposals/csharp-12.0/collection-expressions.md +++ b/proposals/csharp-12.0/collection-expressions.md @@ -10,8 +10,8 @@ Collection expressions introduce a new terse syntax, `[e1, e2, e3, etc]`, to cre Several collection-like types can be created without requiring external BCL support. These types are: * [Array types](https://github.com/dotnet/csharplang/blob/main/spec/types.md#array-types), such as `int[]`. -* [`Span`](https://learn.microsoft.com/dotnet/api/system.span-1) and [`ReadOnlySpan`](https://learn.microsoft.com/dotnet/api/system.readonlyspan-1). -* Types that support [collection initializers](https://github.com/dotnet/csharplang/blob/main/spec/expressions.md#collection-initializers), such as [`List`](https://learn.microsoft.com/dotnet/api/system.collections.generic.list-1). +* [`Span`](/dotnet/api/system.span-1) and [`ReadOnlySpan`](/dotnet/api/system.readonlyspan-1). +* Types that support [collection initializers](https://github.com/dotnet/csharplang/blob/main/spec/expressions.md#collection-initializers), such as [`List`](/dotnet/api/system.collections.generic.list-1). Further support is present for collection-like types not covered under the above through a new attribute and API pattern that can be adopted directly on the type itself. @@ -585,7 +585,7 @@ Not having a *known length* does not prevent any result from being created. Howe The translation may use `stackalloc T1[]` or an [*inline array*](https://github.com/dotnet/csharplang/blob/main/proposals/csharp-12.0/inline-arrays.md) rather than `new T1[]` if [*span-safety*](https://github.com/dotnet/csharplang/blob/main/proposals/csharp-7.2/span-safety.md) is maintained. - * If `T` is some `ReadOnlySpan`, then the literal is translated the same as for the `Span` case except that the final result will be that `Span` [implicitly converted](https://learn.microsoft.com/dotnet/api/system.span-1.op_implicit#system-span-1-op-implicit(system-span((-0)))-system-readonlyspan((-0))) to a `ReadOnlySpan`. + * If `T` is some `ReadOnlySpan`, then the literal is translated the same as for the `Span` case except that the final result will be that `Span` [implicitly converted](/dotnet/api/system.span-1.op_implicit#system-span-1-op-implicit(system-span((-0)))-system-readonlyspan((-0))) to a `ReadOnlySpan`. A `ReadOnlySpan` where `T1` is some primitive type, and all collection elements are constant does not need its data to be on the heap, or on the stack. For example, an implementation could construct this span directly as a reference to portion of the data segment of the program. From 973fe04783dab4fefef6f5f53b5b1f24b79a52eb Mon Sep 17 00:00:00 2001 From: Saisang Cai Date: Fri, 2 Feb 2024 14:25:27 +0800 Subject: [PATCH 3/4] Update inline-arrays.md --- proposals/csharp-12.0/inline-arrays.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/proposals/csharp-12.0/inline-arrays.md b/proposals/csharp-12.0/inline-arrays.md index 41f1511e30..00424e6fc1 100644 --- a/proposals/csharp-12.0/inline-arrays.md +++ b/proposals/csharp-12.0/inline-arrays.md @@ -9,7 +9,7 @@ Provide a general-purpose and safe mechanism for consuming struct types utilizin [InlineArrayAttribute](https://github.com/dotnet/runtime/issues/61135) feature. Provide a general-purpose and safe mechanism for declaring inline arrays within C# classes, structs, and interfaces. -> Note: Previous versions of this spec used the terms "ref-safe-to-escape" and "safe-to-escape", which were introduced in the [Span safety](https://github.com/dotnet/csharplang/blob/main/proposals/csharp-7.2/span-safety.md) feature specification. The [ECMA standard committee](https://www.ecma-international.org/task-groups/tc49-tg2/) changed the names to ["ref-safe-context"](https://learn.microsoft.com/dotnet/csharp/language-reference/language-specification/variables#972-ref-safe-contexts) and ["safe-context"](https://learn.microsoft.com/dotnet/csharp/language-reference/language-specification/structs#16412-safe-context-constraint), respectively. The values of the safe context have been refined to use "declaration-block", "function-member", and "caller-context" consistently. The speclets had used different phrasing for these terms, and also used "safe-to-return" as a synonym for "caller-context". This speclet has been updated to use the terms in the C# 7.3 standard. +> Note: Previous versions of this spec used the terms "ref-safe-to-escape" and "safe-to-escape", which were introduced in the [Span safety](https://github.com/dotnet/csharplang/blob/main/proposals/csharp-7.2/span-safety.md) feature specification. The [ECMA standard committee](https://www.ecma-international.org/task-groups/tc49-tg2/) changed the names to ["ref-safe-context"](/dotnet/csharp/language-reference/language-specification/variables#972-ref-safe-contexts) and ["safe-context"](/dotnet/csharp/language-reference/language-specification/structs#16412-safe-context-constraint), respectively. The values of the safe context have been refined to use "declaration-block", "function-member", and "caller-context" consistently. The speclets had used different phrasing for these terms, and also used "safe-to-return" as a synonym for "caller-context". This speclet has been updated to use the terms in the C# 7.3 standard. ## Motivation @@ -45,7 +45,7 @@ Runtime provides regular GC tracking for all elements in the struct. This proposal will refer to types like this as "inline array types". Elements of an inline array type can be accessed through pointers or through span instances returned by -[System.Runtime.InteropServices.MemoryMarshal.CreateSpan](https://learn.microsoft.com/dotnet/api/system.runtime.interopservices.memorymarshal.createspan)/[System.Runtime.InteropServices.MemoryMarshal.CreateReadOnlySpan](https://learn.microsoft.com/dotnet/api/system.runtime.interopservices.memorymarshal.createreadonlyspan) APIs. However, neither +[System.Runtime.InteropServices.MemoryMarshal.CreateSpan](/dotnet/api/system.runtime.interopservices.memorymarshal.createspan)/[System.Runtime.InteropServices.MemoryMarshal.CreateReadOnlySpan](/dotnet/api/system.runtime.interopservices.memorymarshal.createreadonlyspan) APIs. However, neither the pointer approach, nor the APIs provide type and bounds checking out of the box. Language will provide a type-safe/ref-safe way for accessing elements of inline array types. The access will be span based. @@ -116,20 +116,20 @@ For an inline array element access, the *primary_no_array_creation_expression* o ##### When the expression type is int If *primary_no_array_creation_expression* is a writable variable, the result of evaluating an inline array element access is a writable variable -equivalent to invoking [`public ref T this[int index] { get; }`](https://learn.microsoft.com/dotnet/api/system.span-1.item) with +equivalent to invoking [`public ref T this[int index] { get; }`](/dotnet/api/system.span-1.item) with that integer value on an instance of ```System.Span``` returned by ```System.Span InlineArrayAsSpan``` method on *primary_no_array_creation_expression*. For the purpose of ref-safety analysis the *ref-safe-context*/*safe-context* of the access are equivalent to the same for an invocation of a method with the signature ```static ref T GetItem(ref InlineArrayType array)```. The resulting variable is considered movable if and only if *primary_no_array_creation_expression* is movable. If *primary_no_array_creation_expression* is a readonly variable, the result of evaluating an inline array element access is a readonly variable -equivalent to invoking [`public ref readonly T this[int index] { get; }`](https://learn.microsoft.com/dotnet/api/system.readonlyspan-1.item) with +equivalent to invoking [`public ref readonly T this[int index] { get; }`](/dotnet/api/system.readonlyspan-1.item) with that integer value on an instance of ```System.ReadOnlySpan``` returned by ```System.ReadOnlySpan InlineArrayAsReadOnlySpan``` method on *primary_no_array_creation_expression*. For the purpose of ref-safety analysis the *ref-safe-context*/*safe-context* of the access are equivalent to the same for an invocation of a method with the signature ```static ref readonly T GetItem(in InlineArrayType array)```. The resulting variable is considered movable if and only if *primary_no_array_creation_expression* is movable. If *primary_no_array_creation_expression* is a value, the result of evaluating an inline array element access is a value -equivalent to invoking [`public ref readonly T this[int index] { get; }`](https://learn.microsoft.com/dotnet/api/system.readonlyspan-1.item) with +equivalent to invoking [`public ref readonly T this[int index] { get; }`](/dotnet/api/system.readonlyspan-1.item) with that integer value on an instance of ```System.ReadOnlySpan``` returned by ```System.ReadOnlySpan InlineArrayAsReadOnlySpan``` method on *primary_no_array_creation_expression*. For the purpose of ref-safety analysis the *ref-safe-context*/*safe-context* of the access are equivalent to the same for an invocation of a method with the signature ```static T GetItem(InlineArrayType array)```. @@ -179,13 +179,13 @@ the *primary_no_array_creation_expression*. Then the element access is interpret ##### When the expression implicitly convertible to ```System.Range``` If *primary_no_array_creation_expression* is a writable variable, the result of evaluating an inline array element access is a value -equivalent to invoking [`public Span Slice (int start, int length)`](https://learn.microsoft.com/dotnet/api/system.span-1.slice) +equivalent to invoking [`public Span Slice (int start, int length)`](/dotnet/api/system.span-1.slice) on an instance of ```System.Span``` returned by ```System.Span InlineArrayAsSpan``` method on *primary_no_array_creation_expression*. For the purpose of ref-safety analysis the *ref-safe-context*/*safe-context* of the access are equivalent to the same for an invocation of a method with the signature ```static System.Span GetSlice(ref InlineArrayType array)```. If *primary_no_array_creation_expression* is a readonly variable, the result of evaluating an inline array element access is a value -equivalent to invoking [`public ReadOnlySpan Slice (int start, int length)`](https://learn.microsoft.com/dotnet/api/system.readonlyspan-1.slice) +equivalent to invoking [`public ReadOnlySpan Slice (int start, int length)`](/dotnet/api/system.readonlyspan-1.slice) on an instance of ```System.ReadOnlySpan``` returned by ```System.ReadOnlySpan InlineArrayAsReadOnlySpan``` method on *primary_no_array_creation_expression*. For the purpose of ref-safety analysis the *ref-safe-context*/*safe-context* of the access are equivalent to the same From a7af0693ae6cc73014ce920965f4da1d459bcc92 Mon Sep 17 00:00:00 2001 From: Saisang Cai Date: Fri, 2 Feb 2024 14:26:01 +0800 Subject: [PATCH 4/4] Update speclet-disclaimer.md --- proposals/speclet-disclaimer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/speclet-disclaimer.md b/proposals/speclet-disclaimer.md index c4f873e76c..6bbf228b1d 100644 --- a/proposals/speclet-disclaimer.md +++ b/proposals/speclet-disclaimer.md @@ -1,2 +1,2 @@ > [!NOTE] -> This article is a feature specification. The specification represents the *proposed* feature specification. There may be some discrepancies between the feature specification and the completed implementation. Those differences are captured in the pertinent [language design meeting (LDM) notes](https://github.com/dotnet/csharplang/tree/main/meetings). Links to pertinent meetings are included at the bottom of the spec. You can learn more about the process for merging feature speclets into the C# language standard in the article on the [specifications](https://learn.microsoft.com/dotnet/csharp/language-reference/specifications). +> This article is a feature specification. The specification represents the *proposed* feature specification. There may be some discrepancies between the feature specification and the completed implementation. Those differences are captured in the pertinent [language design meeting (LDM) notes](https://github.com/dotnet/csharplang/tree/main/meetings). Links to pertinent meetings are included at the bottom of the spec. You can learn more about the process for merging feature speclets into the C# language standard in the article on the [specifications](/dotnet/csharp/language-reference/specifications).