{"id":1145,"date":"2018-03-07T14:48:20","date_gmt":"2018-03-07T06:48:20","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/seteplia\/?p=1145"},"modified":"2019-06-11T22:05:36","modified_gmt":"2019-06-12T05:05:36","slug":"the-in-modifier-and-the-readonly-structs-in-c","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/premier-developer\/the-in-modifier-and-the-readonly-structs-in-c\/","title":{"rendered":"The \u2018in\u2019-modifier and the readonly structs in C#"},"content":{"rendered":"

C# 7.2 got two very important features for high-performance scenarios — the readonly structs and the in<\/code> parameters. But to understand why this additions are so important and how they’re related to each other we should look back in history.<\/p>\n

As you probably know, the .NET ecosystem has two family of types — the value types (a.k.a. structs) and the reference types (a.k.a. classes) (*). There are a plenty of differences between them but the main one is the semantics<\/strong>. The value types follow the value semantics: (1) two instances of a value type are equal if all the data members are equal and (2) the value type instance by default is passed around by value, i.e. by creating a copy of the original instance. The reference types, on the other hand, follow the “reference semantics”: (1) two instances of a reference type are equal if they point to the same instance in the managed heap (**) and (2) a reference type instance is passed by reference, i.e. by passing the pointer to the original instance in the managed heap.<\/p>\n

(*) The third category is managed references but for the sake of this discussion we can ignore them. (**) This behavior can be overriden by overriding Equals<\/code> and GetHashCode<\/code>.<\/p>\n

Readonly fields of the value types<\/h4>\n

To enforce the value semantics of value types the C# compiler performs some actions that could be not obvious from the developer’s point of view. Here is an example:<\/p>\n

internal class ReadOnlyEnumerator\r\n{\r\n    private readonly List<int>.Enumerator _enumerator;\r\n\r\n    public ReadOnlyEnumerator(List<int> list)\r\n    {\r\n        Contract.Requires(list.Count >= 1);\r\n        _enumerator = list.GetEnumerator();\r\n    }\r\n\r\n    public void PrintTheFirstElement()\r\n    {\r\n        _enumerator.MoveNext();\r\n        Console.WriteLine(_enumerator.Current);\r\n    }\r\n\r\n}\r\n\r\n\r\nvar roe = new ReadOnlyEnumerator(new List<int>{1,2});\r\nroe.PrintTheFirstElement();<\/pre>\n
The output is not obvious: “0”.<\/p>\n
The readonly<\/code> modifier has slightly different observable effects for the value types and for the reference types. A readonly field of a reference type is like a constant pointer: the compiler will make sure that the field is not reassigned outside the constructor even though the referenced object’s state may change (if the referenced type is mutable). A readonly field of value type means that the value itself should be the same for the entire lifetime of the enclosing instance. To prevent any potential mutations, the compiler makes a defensive copy of the field each time a method or a property is used.<\/p>\n
Under the hood PrintTheFirstElement<\/code> does the following:<\/p>\n
public void PrintTheFirstElement_Decompiled()\r\n{\r\n    \/\/ Defensive copy\r\n    var localEnumerator = _enumerator;\r\n    localEnumerator.MoveNext();\r\n\r\n    \/\/ Defensive copy (2)\r\n    localEnumerator = _enumerator;\r\n    Console.WriteLine(localEnumerator.Current);\r\n}<\/pre>\n
This is a real issue and the reason why mutable value types are evil<\/strong>. A couple of months back I spent a few hours debugging a similar issue caused by a readonly SpinLock<\/code><\/a> field.<\/p>\n
The performance implications of the defensive copies<\/h4>\n
Mutability is not the only problem. The defensive copies can affect performance even when the structs are immutable.<\/p>\n
public struct FairlyLargeStruct\r\n{\r\n    private readonly long l1, l2, l3, l4;\r\n    public int N { get; }\r\n    public FairlyLargeStruct(int n) : this() => N = n;\r\n}<\/pre>\n
Let’s see what the difference between readonly<\/code> and non-readonly<\/code> access of the field:<\/p>\n
private FairlyLargeStruct _nonReadOnlyStruct = new FairlyLargeStruct(42);\r\nprivate readonly FairlyLargeStruct _readOnlyStruct = new FairlyLargeStruct(42);\r\nprivate readonly int[] _data = Enumerable.Range(1, 100_000).ToArray();\r\n        \r\n[Benchmark]\r\npublic int AggregateForNonReadOnlyField()\r\n{\r\n    int result = 0;\r\n    foreach (int n in _data)\r\n        result += n + _nonReadOnlyStruct.N;\r\n    return result;\r\n}\r\n\r\n[Benchmark]\r\npublic int AggregateForReadOnlyField()\r\n{\r\n    int result = 0;\r\n    foreach (int n in _data)\r\n        result += n + _readOnlyStruct.N;\r\n    return result;\r\n}<\/pre>\n
The results are:<\/p>\n
                       Method |      Mean |    Error |    StdDev | \r\n----------------------------- |----------:|---------:|----------:| \r\n AggregateForNonReadOnlyField |  87.92 us | 1.800 us |  3.677 us | \r\n    AggregateForReadOnlyField | 148.29 us | 4.226 us | 12.460 us |<\/pre>\n
The significant difference in the results caused by a defensive copy that is happening each time the readonly field is used. You may have heard that the size of the struct should be relatively small to avoid the overhead of passing it around to other methods. But as you can see, you may get a performance hit even when a fairly large struct is stored in a readonly field and never passed to another method.<\/p>\n
There are at least 3 solutions to this problem:<\/p>\n
1. Use fields instead of properties<\/strong><\/p>\n
public struct FairlyLargeStruct\r\n{\r\n    private readonly long l1, l2, l3, l4;\r\n    public readonly int N;\r\n    public FairlyLargeStruct(int n) : this() => N = n;\r\n}<\/pre>\n
If the C# compiler sees an access to a FairlyLargeStruct<\/code>‘s field N<\/code> via readonly<\/code>variable, it won’t create a defensive copy, because it knows that reading a field N<\/code> is side effect free. This solution is not sustainable for a real world because FairlyLargeStruct<\/code> could have methods as well, and even if there are no methods or properties today, it’s just a matter of time when someone from your team will refactor the code to switch from fields to properties causing a performance regression.<\/p>\n
2. Use non-readonly field of FairlyLargeStruct<\/code><\/strong><\/p>\n
\/\/ Use non-readonly field to avoid redundant defensive copy on each field access\r\nprivate \/*readonly*\/FairlyLargeStruct _fairlyLargeStruct;<\/pre>\n
3. Use readonly structs<\/strong><\/p>\n
public readonly struct FairlyLargeStruct\r\n{\r\n    private readonly long l1, l2, l3, l4;\r\n    public int N { get; }\r\n    public FairlyLargeStruct(int n) : this() => N = n;\r\n}<\/pre>\n
The readonly structs<\/h4>\n
C# 7.2 allows a user to enforce immutability for a given struct by using the readonly<\/code>modifier. As you may see in a moment it is good for performance but it is also very useful from a design perspective: readonly structs clearly carries the intention that the instance is immutable and can’t be changed (without some tricks like reflection).<\/p>\n
The reaodnly<\/code> modifier enforces the following behavior:<\/p>\n
    \n
  1. The compiler checks that the struct is indeed immutable and consists only of readonly fields and\/or readonly properties (properties like public int Foo {get; private set;}<\/code> are not readonly).<\/li>\n
  2. Allows the compiler to skip defensive copies in some contexts, like when a readonly field of such a struct is used.<\/li>\n<\/ol>\n
    Here are the benchmark results for readonly struct FairlyLargeStruct<\/code>:<\/p>\n
                           Method |     Mean |    Error |   StdDev | \r\n----------------------------- |---------:|---------:|---------:| \r\n AggregateForNonReadOnlyField | 91.19 us | 1.811 us | 2.597 us | \r\n    AggregateForReadOnlyField | 89.25 us | 1.775 us | 3.705 us |<\/pre>\n
    The in<\/code>-modifier<\/h4>\n
    The very first version of the C# language had 3 ways of passing the arguments: by value (no modifier), by reference (with ref<\/code> modifier) and as an output parameter (with out<\/code> modifier) (***)<\/p>\n
    (***) Under the hood the CLR has only two options: passing by value and passing by reference. The out<\/code> modifier is the same as ref<\/code> modifier plus the compiler checks for definite assignment.<\/p>\n
    C# 7.2 introduces the third way of passing arguments: using in<\/code>-modifier.<\/p>\n
    The in<\/code>-modifier is a way to pass the argument via readonly reference. Under the hood, the argument is passed by reference with a special attribute (System.Runtime.CompilerServices.IsReadOnlyAttribute<\/code>), and the compiler makes sure that the method does not modify the parameter.<\/p>\n
    public void Foo(in string s)\r\n{\r\n    \/\/ Cannot assign to variable 'in string' because it is a readonly variable\r\n    s = string.Empty;\r\n}<\/pre>\n
    This simple language change has a large set of consequences.<\/p>\n
      \n
    1. You can’t create an overload that differs only by in<\/code>, ref<\/code>, out<\/code>. This is expected, because the in<\/code> modifier is the same the ref<\/code>-modifier under the hood with some additional logic from the compiler.<\/li>\n
    2. You can’t use the in<\/code>-modifier for async methods and iterator blocks.<\/li>\n<\/ol>\n
      \/\/ Async methods cannot have ref or out parameters\r\nasync Task ByInAsync(in string s) => await Task.Yield();<\/pre>\n
      This is expected as well because you can’t use ref<\/code>\/out<\/code> modifiers in these contexts as well. The restriction is just a side-effect of how async methods are implemented<\/a>https:\/\/blogs.msdn.microsoft.com\/seteplia\/2017\/11\/30\/dissecting-the-async-methods-in-c\/<\/a>.<\/p>\n
        \n
      1. You can<\/strong> pass a variable from a using block as an in<\/code>-argument, even though it is impossible for ref<\/code>\/out<\/code> parameters:<\/li>\n<\/ol>\n
        struct Disposable : IDisposable\r\n{\r\n    public void Dispose() { }\r\n}\r\n\r\npublic void DisposableSample()\r\n{\r\nusing (var d = new Disposable())\r\n{\r\n    \/\/ Ok\r\n    ByIn(d);\r\n    \/\/ Cannot use 'd' as a ref or out value because it is a 'using variable'\r\n    \/\/ByRef(ref d);\r\n}\r\n\r\nvoid ByRef(ref Disposable disposable) { }\r\nvoid ByIn(in Disposable disposable) { }<\/pre>\n
        This is already interesting. Apparently, the restriction that ‘using variable’ cannot be passed by reference is the compiler restriction, not the CLR one. And in this case, the restriction is removed because it is indeed safe to pass the variable as in<\/code> argument.<\/p>\n
          \n
        1. Default values for in<\/code>-parameters Here is another difference between in<\/code>-parameters and ref<\/code>\/out<\/code>: the in<\/code>-parameter could have a default value:<\/li>\n<\/ol>\n
          public int ByIn(in string s = \"\") => s.Length;<\/pre>\n
            \n
          1. You can<\/strong> make an overload that differs only by in<\/code> modifier:<\/li>\n<\/ol>\n
            public int Foo(in string s) => s.Length;\r\npublic int Foo(string s) => s.Length;<\/pre>\n
            This case is tricky because the behavior is language-version-specific. For instance, in C# 7.2 (the first version that added this feature), it was impossible to call the second overload:<\/p>\n
            string s = string.Empty;\r\nFoo(in s);\r\n\/\/ The call is ambiguous between the following methods or properties: \r\n\/\/ 'WeirdOverload.Foo(in string)' and 'WeirdOverload.Foo(string)'\r\nFoo(s);<\/pre>\n
            But this behavior was fixed<\/a> in C# 7.3 and now, Foo(s)<\/code> is resolved to Foo(string s)<\/code>.<\/p>\n
            But why the in<\/code>-modifier is optional on the call-site? As we’ll see in a moment, in<\/code>-modifier can be very useful for high-performance scenarios, and this behavior simplifies the adoption of this feature:<\/p>\n
            public int ByIn(in string s) => s.Length;\r\n\r\n\r\nstring s = string.Empty;\r\nByIn(in s); \/\/ Works fine\r\nByIn(s); \/\/ Works fine as well!\r\n\/\/ Fail?!?! An expression cannot be used in this context because it may not be passed or returned by reference\r\nByIn(in \"some string\");\r\nByIn(\"some string\"); \/\/ Works fine!<\/pre>\n
            The behavior looks a bit inconsistent (all the other ref<\/code>-like parameters should be passed using in<\/code> or out<\/code> keyword), the ability to omit the in<\/code>-modifier makes a perfect sense to me (*****). Let suppose you’ve changed a library code to pass some fairly large struct using the in<\/code>-modifier. You don’t want every client of your library to change the call site of this method in order to benefit from your change.<\/p>\n
            (*****) What does not make sense to me at all is the error when the in<\/code>-modifier is used with the literal.<\/p>\n
            As you can see the in<\/code>-modifier is a bit trickier than you might think. Semantically it is just another form of “input” parameters, very similar to passing an argument by value. On the other hand the in<\/code>-modifier is implemented as a ref<\/code>-parameter making some scenarios like async methods, impossible.<\/p>\n
            But even with the existing restrictions, the new modifier is fairly useful because it helps to express the intent more clearly, and, as we’ll see in a moment, it helps in terms of performance.<\/p>\n
            Performance characteristics of the in<\/code>-modifier<\/h4>\n
            The in<\/code> parameters of value types are passed by reference, and that means that the cost of passing an argument is constant and doesn’t depend on the size of the struct. This is a good news. But I have a bad news as well.<\/p>\n
            Let’s change the original benchmark a little bit:<\/p>\n
            public struct FairlyLargeStruct\r\n{\r\n    private readonly long l1, l2, l3, l4;\r\n    public int N { get; }\r\n    public FairlyLargeStruct(int n) : this() => N = n;\r\n}\r\n\r\n\r\nprivate readonly int[] _data = Enumerable.Range(1, 100_000).ToArray();\r\n\r\n[Benchmark]\r\npublic int AggregatePassedByValue()\r\n{\r\n    return DoAggregate(new FairlyLargeStruct(42));\r\n\r\n    int DoAggregate(FairlyLargeStruct largeStruct)\r\n    {\r\n        int result = 0;\r\n        foreach (int n in _data)\r\n            result += n + largeStruct.N;\r\n        return result;\r\n    }\r\n}\r\n\r\n[Benchmark]\r\npublic int AggregatePassedByIn()\r\n{\r\n    return DoAggregate(new FairlyLargeStruct(42));\r\n\r\n    int DoAggregate(in FairlyLargeStruct largeStruct)\r\n    {\r\n        int result = 0;\r\n        foreach (int n in _data)\r\n            result += n + largeStruct.N;\r\n        return result;\r\n    }\r\n}<\/pre>\n
            Note, that FairlyLargeStruct<\/code> struct is a normal struct, not a readonly one. Here are the results:<\/p>\n
                             Method |      Mean |     Error |    StdDev | \r\n----------------------- |----------:|----------:|----------:| \r\n AggregatePassedByValue |  71.24 us | 0.3150 us | 0.2278 us | \r\n    AggregatePassedByIn | 124.02 us | 3.2885 us | 9.6963 us |<\/pre>\n
            Remember I’ve mentioned that the in<\/code> parameters are similar to the readonly fields? To make sure that the parameter’s value stays the same the compiler make a defensive copy of the parameter every time a method\/property is used. If the struct is readonly then the compiler removes the defensive copy the same way as it does for readonly fields.<\/p>\n
            It means that you should never pass a non-readonly struct as in<\/code> parameter<\/strong>. It almost always will make the performance worse. Yes, the argument passing is cheaper, but once the parameter is used, the defensive copy will nullify the benefits or will make the performance worse. It could make sense if the struct is a C-like struct with a bunch of public fields and everyone in the team is aware that changing fields to properties would have a drastic performance impact on the application. But in this case, I would suggest passing the struct by reference instead.<\/p>\n
            Conclusion<\/h4>\n
              \n
            • The readonly structs are very useful from the design and the performance points of view.<\/li>\n
            • If the size of a readonly struct is bigger than IntPtr.Size<\/code> you should pass it as an in<\/code>-parameter for performance reasons.<\/li>\n
            • You may consider using the in<\/code>-parameters for reference types to express your intent more clearly.<\/li>\n
            • You should never use a non-readonly struct as the in<\/code> parameters because it may negatively affect performance and could lead to an obscure behavior if the struct is mutable.<\/li>\n<\/ul>\n","protected":false},"excerpt":{"rendered":"
              C# 7.2 got two very important features for high-performance scenarios — the readonly structs and the in parameters. But to understand why this additions are so important and how they’re related to each other we should look back in history. As you probably know, the .NET ecosystem has two family of types — the value […]<\/p>\n","protected":false},"author":4004,"featured_media":37840,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[6699],"tags":[6695],"class_list":["post-1145","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-c","tag-seteplia"],"acf":[],"blog_post_summary":"
              C# 7.2 got two very important features for high-performance scenarios — the readonly structs and the in parameters. But to understand why this additions are so important and how they’re related to each other we should look back in history. As you probably know, the .NET ecosystem has two family of types — the value […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/posts\/1145","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/users\/4004"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/comments?post=1145"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/posts\/1145\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/media\/37840"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/media?parent=1145"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/categories?post=1145"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/premier-developer\/wp-json\/wp\/v2\/tags?post=1145"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}