From fc19f43caac72564432262d539901386ae21c876 Mon Sep 17 00:00:00 2001 From: anonymousgituser <31715568+anonymousgituser@users.noreply.github.com> Date: Mon, 19 Mar 2018 21:52:48 -0400 Subject: [PATCH 1/8] Update to article on In Parameter Modifiers Removed mention of "in" parameters being especially useful for arrays of structures given arrays are reference types already. Added note about benefit of copying by reference for value types. Included warning about using "in" parameters with structs not defined as readonly. Added "Reference Semantics with Value Types" to "See Also" section. --- .../language-reference/keywords/in-parameter-modifier.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/csharp/language-reference/keywords/in-parameter-modifier.md b/docs/csharp/language-reference/keywords/in-parameter-modifier.md index 23b2a3c5cd34a..3f9f4a67ed401 100644 --- a/docs/csharp/language-reference/keywords/in-parameter-modifier.md +++ b/docs/csharp/language-reference/keywords/in-parameter-modifier.md @@ -56,7 +56,10 @@ You can't use the `in`, `ref`, and `out` keywords for the following kinds of met - Iterator methods, which include a [yield return](../../../csharp/language-reference/keywords/yield.md) or `yield break` statement. -You typically declare `in` arguments to avoid the copy operations necessary for passing arguments by value. This is most useful when arguments are structures or arrays of structures. +You typically declare `in` arguments to avoid the copy operations necessary for passing arguments by value. This is most useful when arguments are value types such as structures where copy operations are more expensive than passing by reference. + +> [!WARNING] +> `in` parameters can be even more expensive if misused. The compiler cannot know if any member method modifies the state of the struct. To ensure that the object is not modified, the compiler creates a copy and calls member references using that copy. Any modifications are to that defensive copy. Given this, you should consider defining structures as `readonly struct`. ## C# Language Specification [!INCLUDE[CSharplangspec](~/includes/csharplangspec-md.md)] @@ -66,3 +69,4 @@ You typically declare `in` arguments to avoid the copy operations necessary for [C# Programming Guide](../../../csharp/programming-guide/index.md) [C# Keywords](../../../csharp/language-reference/keywords/index.md) [Method Parameters](../../../csharp/language-reference/keywords/method-parameters.md) + [Reference Semantics with Value Types](../../../csharp/reference-semantics-with-value-types.md) From 47ec400dc34f25a146b17732f73bad4c3b761821 Mon Sep 17 00:00:00 2001 From: anonymousgituser <31715568+anonymousgituser@users.noreply.github.com> Date: Mon, 19 Mar 2018 23:18:12 -0400 Subject: [PATCH 2/8] Update to Article on Ref Keyword Added information concerning using "ref" keyword to handle variable by reference. --- docs/csharp/language-reference/keywords/ref.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/csharp/language-reference/keywords/ref.md b/docs/csharp/language-reference/keywords/ref.md index f75b0a0bd1494..61ed20196d8ea 100644 --- a/docs/csharp/language-reference/keywords/ref.md +++ b/docs/csharp/language-reference/keywords/ref.md @@ -22,7 +22,7 @@ The `ref` keyword indicates a value that is passed by reference. It is used in t - In a method signature, to return a value to the caller by reference. See [Reference return values](#reference-return-values) for more information. -- In a member body, to indicate that a reference return value is stored locally as a reference that the caller intends to modify. See [Ref locals](#ref-locals) for more information. +- In a member body, to indicate that a reference return value is stored locally as a reference that the caller intends to modify or, in general, a local variable accesses another value by reference. See [Ref locals](#ref-locals) for more information. ## Passing an argument by reference @@ -104,7 +104,13 @@ For example, the following statement defines a ref local value that is returned ref decimal estValue = ref Building.GetEstimatedValue(); ``` -Note that the `ref` keyword must be used in both places, or the compiler generates error CS8172, "Cannot initialize a by-reference variable with a value." +You can access a value by reference in the same way. In some cases, accessing a value by reference increases performance by avoiding a potentially expensive copy operation. For example, the following statement shows how one can define a ref local value that is used to reference a value. + +```csharp +ref VeryLargeStruct reflocal = ref veryLargeStruct; +``` + +Note that in both examples the `ref` keyword must be used in both places, or the compiler generates error CS8172, "Cannot initialize a by-reference variable with a value." ## A ref returns and ref locals example From ff8a4866cb0401acc497aa1672551003f13c4385 Mon Sep 17 00:00:00 2001 From: anonymousgituser <31715568+anonymousgituser@users.noreply.github.com> Date: Mon, 19 Mar 2018 23:36:20 -0400 Subject: [PATCH 3/8] Update to Article on "Reference semantics with value types" Added section on readonly ref structures. --- .../csharp/reference-semantics-with-value-types.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/csharp/reference-semantics-with-value-types.md b/docs/csharp/reference-semantics-with-value-types.md index 02900332e18da..d47e66f6f1517 100644 --- a/docs/csharp/reference-semantics-with-value-types.md +++ b/docs/csharp/reference-semantics-with-value-types.md @@ -202,6 +202,20 @@ types. These restrictions ensure that you do not accidentally use a `ref struct` in a manner that could promote it to the managed heap. +## `readonly ref struct` type + +Declaring a struct as `readonly ref` combines the benefits and restrictions of `ref struct` and `readonly struct` delcarations. + +The following example demonstrates the declaration of `readonly ref struct`. + +```csharp +readonly ref struct RefReadOnlyPoint2D +{ + public int X { get; } + public int Y { get; } +} +``` + ## Conclusions These enhancements to the C# language are designed for performance critical From 6fec6914a0c615f833db627d808588fc25155458 Mon Sep 17 00:00:00 2001 From: anonymousgituser <31715568+anonymousgituser@users.noreply.github.com> Date: Mon, 19 Mar 2018 23:54:40 -0400 Subject: [PATCH 4/8] Whitespace adjustment --- .../csharp/language-reference/keywords/in-parameter-modifier.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/csharp/language-reference/keywords/in-parameter-modifier.md b/docs/csharp/language-reference/keywords/in-parameter-modifier.md index 3f9f4a67ed401..ce082c585d6d8 100644 --- a/docs/csharp/language-reference/keywords/in-parameter-modifier.md +++ b/docs/csharp/language-reference/keywords/in-parameter-modifier.md @@ -68,5 +68,5 @@ You typically declare `in` arguments to avoid the copy operations necessary for [C# Reference](../../../csharp/language-reference/index.md) [C# Programming Guide](../../../csharp/programming-guide/index.md) [C# Keywords](../../../csharp/language-reference/keywords/index.md) - [Method Parameters](../../../csharp/language-reference/keywords/method-parameters.md) + [Method Parameters](../../../csharp/language-reference/keywords/method-parameters.md) [Reference Semantics with Value Types](../../../csharp/reference-semantics-with-value-types.md) From 810782d7998904f43083026c6cd1e94aa318faa4 Mon Sep 17 00:00:00 2001 From: anonymousgituser <31715568+anonymousgituser@users.noreply.github.com> Date: Mon, 19 Mar 2018 23:55:29 -0400 Subject: [PATCH 5/8] Update to Article "Ref returns and ref locals" Added example and brief explanation for ref locals used to reference variables. --- .../classes-and-structs/ref-returns.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/csharp/programming-guide/classes-and-structs/ref-returns.md b/docs/csharp/programming-guide/classes-and-structs/ref-returns.md index 26dbf673a05b1..e33f4020622f2 100644 --- a/docs/csharp/programming-guide/classes-and-structs/ref-returns.md +++ b/docs/csharp/programming-guide/classes-and-structs/ref-returns.md @@ -80,7 +80,15 @@ ref Person p = ref contacts.GetContactInformation("Brandie", "Best"); Subsequent usage of `p` is the same as using the variable returned by `GetContactInformation` because `p` is an alias for that variable. Changes to `p` also change the variable returned from `GetContactInformation`. -Note that the `ref` keyword is used both before the local variable declaration *and* before the method call. Failure to include both `ref` keywords in the variable declaration and assignment results in compiler error CS8172, "Cannot initialize a by-reference variable with a value." +Note that the `ref` keyword is used both before the local variable declaration *and* before the method call. + +You can access a value by reference in the same way. In some cases, accessing a value by reference increases performance by avoiding a potentially expensive copy operation. For example, the following statement shows how one can define a ref local value that is used to reference a value. + +```csharp +ref VeryLargeStruct reflocal = ref veryLargeStruct; +``` + +Note that the `ref` keyword is used both before the local variable declaration *and* before the value in the second example. Failure to include both `ref` keywords in the variable declaration and assignment in both examples results in compiler error CS8172, "Cannot initialize a by-reference variable with a value." ## Ref returns and ref locals: an example @@ -96,4 +104,5 @@ Without support for reference return values, such an operation is usually perfor ## See also -[ref keyword](../../language-reference/keywords/ref.md) +[ref keyword](../../language-reference/keywords/ref.md) +[Reference Semantics with Value Types](../../../csharp/reference-semantics-with-value-types.md) From 54e0e710342f2f3891bed8a9840a4eab3c84d77f Mon Sep 17 00:00:00 2001 From: anonymousgituser <31715568+anonymousgituser@users.noreply.github.com> Date: Tue, 20 Mar 2018 00:00:07 -0400 Subject: [PATCH 6/8] Naming tweak. --- docs/csharp/reference-semantics-with-value-types.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/csharp/reference-semantics-with-value-types.md b/docs/csharp/reference-semantics-with-value-types.md index d47e66f6f1517..b09a7f39c6804 100644 --- a/docs/csharp/reference-semantics-with-value-types.md +++ b/docs/csharp/reference-semantics-with-value-types.md @@ -209,7 +209,7 @@ Declaring a struct as `readonly ref` combines the benefits and restrictions of ` The following example demonstrates the declaration of `readonly ref struct`. ```csharp -readonly ref struct RefReadOnlyPoint2D +readonly ref struct ReadOnlyRefPoint2D { public int X { get; } public int Y { get; } From 24a9ea54e8013e9fcb994ca8154c891848da6f43 Mon Sep 17 00:00:00 2001 From: anonymousgituser <31715568+anonymousgituser@users.noreply.github.com> Date: Wed, 21 Mar 2018 19:18:56 -0400 Subject: [PATCH 7/8] Updated reference-semantics-with-value-types.md per @BillWagner's suggestion --- docs/csharp/reference-semantics-with-value-types.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/csharp/reference-semantics-with-value-types.md b/docs/csharp/reference-semantics-with-value-types.md index b09a7f39c6804..ec69f4e5f1779 100644 --- a/docs/csharp/reference-semantics-with-value-types.md +++ b/docs/csharp/reference-semantics-with-value-types.md @@ -213,6 +213,8 @@ readonly ref struct ReadOnlyRefPoint2D { public int X { get; } public int Y { get; } + + ReadOnlyRefPoint2D(int x, int y) => (X, Y) = (x, y); } ``` From 737a4ebe30db3b7210112ade88bc318c857c2e1c Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Wed, 21 Mar 2018 20:05:58 -0400 Subject: [PATCH 8/8] Update in-parameter-modifier.md --- .../csharp/language-reference/keywords/in-parameter-modifier.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/csharp/language-reference/keywords/in-parameter-modifier.md b/docs/csharp/language-reference/keywords/in-parameter-modifier.md index ce082c585d6d8..7b425dd268c70 100644 --- a/docs/csharp/language-reference/keywords/in-parameter-modifier.md +++ b/docs/csharp/language-reference/keywords/in-parameter-modifier.md @@ -59,7 +59,7 @@ You can't use the `in`, `ref`, and `out` keywords for the following kinds of met You typically declare `in` arguments to avoid the copy operations necessary for passing arguments by value. This is most useful when arguments are value types such as structures where copy operations are more expensive than passing by reference. > [!WARNING] -> `in` parameters can be even more expensive if misused. The compiler cannot know if any member method modifies the state of the struct. To ensure that the object is not modified, the compiler creates a copy and calls member references using that copy. Any modifications are to that defensive copy. Given this, you should consider defining structures as `readonly struct`. +> `in` parameters can be even more expensive if misused. The compiler may not know if member methods modify the state of the struct. Whenever the compiler cannot ensure that the object is not modified, it defensively creates a copy and calls member references using that copy. Any possible modifications are to that defensive copy. The two ways to avoid these copies are to pass `in` parameters as `in` arguments or to define structures as `readonly struct`. ## C# Language Specification [!INCLUDE[CSharplangspec](~/includes/csharplangspec-md.md)]