Skip to content

Updates to Articles Concerning Ref Locals, In Parameters, and Readonly Ref Structs - #4710

Merged
BillWagner merged 8 commits into
dotnet:masterfrom
anonymousgituser:proposed_2018_03_19
Mar 22, 2018
Merged

BillWagner merged 8 commits into
dotnet:masterfrom
anonymousgituser:proposed_2018_03_19

Conversation

@anonymousgituser

Copy link
Copy Markdown
Contributor

Updates to Articles Concerning Ref Locals, In Parameters, and Readonly Ref Structs

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. Additional scrutiny by maintainers may be needed for this change as I may have misinterpreted the purpose of the original remark: "This is most useful when arguments are structures or arrays of structures."
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.

Update to Article on Ref Keyword

Added information concerning using "ref" keyword to handle variable by reference.

Update to Article on "Reference semantics with value types"

Added section on readonly ref structures.

Update to Article "Ref returns and ref locals"

Added example and brief explanation for ref locals used to reference variables.

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.
Added information concerning using "ref" keyword to handle variable by reference.
Added section on readonly ref structures.
Added example and brief explanation for ref locals used to reference variables.
@BillWagner

Copy link
Copy Markdown
Member

Thanks for submitting this @anonymousgituser We appreciate it.

I've given everything a first look, and I like the direction. There are a couple places where I want to think about wording a bit before merging:

  1. You're right on the array comment. I was thinking about Span<T> like structures, but hadn't introduced that yet and wanted to keep it simple. I may not come up with better wording, but I want to think a bit.
  2. The warning needs a bit more nuanced language. A more common scenario is passing an in parameter to a method that uses by-value parameters. And, some work in 7.3 will mean that the compiler can sometimes know that fields aren't modified in struct member methods.

I'll have full comments no later than tomorrow.

@BillWagner BillWagner left a comment

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.

Overall, this looks great @anonymousgituser Thanks for spotting these and improving this.

I had one wording change, and one sample update. Can you add those to your branch, and then I'll :shipit:

Just @ - mention me after those updates.

Thanks again. We appreciate the thoughtful contributions to make this topic more clear.

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`.

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.

How about this update for the warning text:

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.


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.

- 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!

@BillWagner

Copy link
Copy Markdown
Member

Thanks for the update, @anonymousgituser I've approved this PR, and I'll merge it as soon as the build finishes.

The changes should appear on the live site in the next couple days, on our regular publish cycle.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants