Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The more I thought about this, the more I liked your proposed wording. Let's :shipit:

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great catch on the example.

I have committed the change.

Thanks for your thorough review and help with this @BillWagner!


> [!WARNING]
> `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)]
Expand All @@ -65,4 +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)
10 changes: 8 additions & 2 deletions docs/csharp/language-reference/keywords/ref.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down
13 changes: 11 additions & 2 deletions docs/csharp/programming-guide/classes-and-structs/ref-returns.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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)
16 changes: 16 additions & 0 deletions docs/csharp/reference-semantics-with-value-types.md
Original file line number Diff line number Diff line change
Expand Up @@ -202,6 +202,22 @@ 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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need a better example here. I'd suggest adding the following constructor:

ReadOnlyRefPoint2D(int x, int y) => (X, Y) = (x, y);

Otherwise, X and Y can only have the value 0.

readonly ref struct ReadOnlyRefPoint2D
{
public int X { get; }
public int Y { get; }

ReadOnlyRefPoint2D(int x, int y) => (X, Y) = (x, y);
}
```

## Conclusions

These enhancements to the C# language are designed for performance critical
Expand Down