[API Proposal]: InlineArrayAttribute

[VSadov]

Background and motivation

There were multiple proposals and ideas in the past asking for a no-indirection primitive for inline data. Example1(inline strings), Example2(inline arrays), Example3(generalized fixed-buffers)
Our existing offering in this area – unsafe fixed-sized buffers has multiple constraints, in particular it works only with blittable value types and provides no overrun/type safety, which considerably limits its use.

In the recent hackathon we have explored a possibility of introducing a primitive for efficient, type-safe, overrun-safe indexable/sliceable inline data and it appears to be possible with relatively modest investments in the runtime.

API Proposal

namespace System.Runtime.CompilerServices
{
    [AttributeUsage(AttributeTargets.Struct, AllowMultiple = false)]
    public sealed class InlineArrayAttribute : Attribute
    {
        public InlineArrayAttribute (int length)
        {
            Length = length;
        }

        public int Length { get; }
    }
}

When InlineArray attribute is applied to a struct with one instance field, it is interpreted by the runtime as a directive to replicate the layout of the struct Length times. That includes replicating GC tracking information if the struct happens to contain managed pointers.

Unlike "filed0; field1; field2;..." approach, the resulting layout would be guaranteed to have the same order and packing details as elements of an array with element [0] matching the location of the single specified field.
That will allow the whole aggregate to be safely indexable/sliceable.

Length must be greater than 0.

struct must not have explicit layout.

In cases when the attribute cannot have effect, it is an error case handled in the same way as the given platform handles cases when a type layout cannot be constructed.
Generally, it would be a TypeLoadException thrown at the time of layout construction.

API Usage

// runtime replicates the layout of the struct 42 times 
[InlineArray(Length = 42)] 
struct MyArray<T> 
{ 
    private T _element0; 
    public Span<T> SliceExample() 
    { 
        return MemoryMarshal.CreateSpan(ref _element0, 42); 
    } 
} 

For more details on how this attribute could be used on the Roslyn side see Low Level Struct Improvements document.

Alternative Designs

During hackathon we have also explored an approach where the length is specified via a type parameter and arrays of concrete lengths are created by the way of generic instantiation - ValueArray<T, Size>.

Such approach moves some of the effort in creation of concrete struct arrays from the user to the runtime.
However in the current .NET IL/metadata standard, the Size parameter would need to be an integer constant encoded as a type. While such encodings are possible, finding one that everybody could comfortably accept has been an issue that we could not resolve.

Risks

InlineArrayAttribute requires runtime cooperation to function correctly. On downlevel runtimes the attribute will not have any effect, contrary to the assumptions in the code that implements slicing or indexing.

FAQ:

Why do we put the attribute on the struct and not on the field?

Allowing the attribute on individual fields introduces numerous additional scenarios and combinations that make the feature considerably more complex.

• we would need to rationalize or somehow forbid the attribute usage on static, threadstatic, RVA fields
• allowing replicated storage in classes would need to account for base classes that also may have instance fields, and perhaps with replicated storage as well.
• allowing multiple replicated fields in the same struct could make the overall layout computation a fairly complex routine when field ordering, packing, ref-ness and alignment of the fields are considered. (i.e alignment would need to consider pre-replicated sizes, but packing post-replicated)

All the above issues can be solved, but at a cost to the implementation complexity while most additional scenarios appear to be less common and easily solvable by providing a wrapper struct.

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.

[VSadov]

CC: @jaredpar @davidwrighton @jkotas @stephentoub

Tagging subscribers to this area: @dotnet/area-system-runtime
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

There were multiple proposals and ideas in the past asking for a no-indirection primitive for inline data. Example1(inline strings), Example2(inline arrays), Example3(generalized fixed-buffers)
Our existing offering in this area – unsafe fixed-sized buffers has multiple constraints, in particular it works only with blittable value types and provides no overrun/type safety, which considerably limits its use.

In the recent hackathon we have explored a possibility of introducing a primitive for efficient, type-safe, overrun-safe indexable/sliceable inline data and it appears to be possible with relatively modest investments in the runtime.

API Proposal

namespace System.Runtime.CompilerServices
{
    [AttributeUsage(AttributeTargets.Struct, AllowMultiple = false)]
    public sealed class InlineArrayAttribute : Attribute
    {
        public InlineArrayAttribute (int length)
        {
            Length = length;
        }

        public int Length { get; }
    }
}

When InlineArray attribute is applied to a struct with one instance field, it is interpreted by the runtime as a directive to replicate the layout of the struct Length times. That includes replicating GC tracking information if the struct happen to contain managed pointers.

Unlike "filed0; field1; field2;..." approach, the resulting layout would be guaranteed to have the same order and packing details as elements of an array with element [0] matching the location of the single specified field.
That will allow the whole aggregate to be safely indexable/sliceable.

Length must be greater than 0 and otherwise ignored.

API Usage

// runtime replicates the layout of the struct 42 times 
[InlineArray(Length = 42)] 
struct MyArray<T> 
{ 
    private T _element0; 
    public Span<T> SliceExample() 
    { 
        return MemoryMarshal.CreateSpan(ref _element0, 42); 
    } 
} 

For more details on how this attribute could be used on the Roslyn side see Low Level Struct Improvements document.

Alternative Designs

In hackathon we have also explored an approach where the length is specified via a type parameter and arrays of concrete lengths are created by the way of generic instantiation - ValueArray<T, Size>.

Such approach moves some of the effort in creation of concrete struct arrays from the user to the runtime.
However in the current .NET IL/metadata standard, the Size parameter would need to be an integer constant encoded as a type. While such encodings are possible, finding one that everybody could comfortably accept has been an issue that we could not resolve.

Risks

InlineArrayAttribute requires runtime cooperation to function correctly. On downlevel runtimes the attribute will not have any effect, contrary to the code that implements slicing or indexing.

As such the use of the attribute should be versioned with a mechanism such as runtime feature flags.

FAQ:

Why do we put the attribute on the struct and not on the field?

Allowing the attribute on individual fields introduces numerous additional scenarios and combinations that make the feature considerably more complex.

• we would need to rationalize or somehow forbid the attribute usage on static, threadstatic, RVA fields
• allowing replicated storage in classes would need to account for base classes that also may have instance fields, and perhaps with replicated storage as well.
• allowing multiple replicated fields in the same struct could make the overall layout computation a fairly complex routine when field ordering, packing, ref-ness and alignment of the fields are considered. (i.e alignment would need to consider pre-replicated sizes, but packing post-replicated)

All the above issues can be solved, but at a cost to the implementation complexity while most additional scenarios appear to be less common and easily solvable by providing a wrapper struct.

Author:	VSadov
Assignees:	-
Labels:	api-suggestion, area-System.Runtime, untriaged
Milestone:	-

[jkotas]

I think this is ready for API review.

[lambdageek]

1. I think Length = 0 should be allowed nevermind... I think I don't like it, actualliy.

2. What kind of validation do we want on the runtime side? E.g. throw BadImageFormatException if the length is negative non-positive, or if the struct has multiple fields.

3. Is this ok:

    [InlineArray(Length = 10)]
    struct Tenner<T> where T : class {
       public T element0;
    }

   How about:

    [InlineArray(Length = 10)]
    struct Tenner<T> {
       public T element0;
    }

[Sergio0694]

"During hackathon we have also explored an approach where the length is specified via a type parameter and arrays of concrete lengths are created by the way of generic instantiation - ValueArray<T, Size>."

"Such approach moves some of the effort in creation of concrete struct arrays from the user to the runtime.
However in the current .NET IL/metadata standard, the Size parameter would need to be an integer constant encoded as a type. While such encodings are possible, finding one that everybody could comfortably accept has been an issue that we could not resolve."

[VSadov]

I think Length = 0 should be allowed nevermind... I think I don't like it, actualliy.

I do not think we have a choice. We cannot remove the field that is already there, thus we cannot follow the directive to have a completely empty array.

What kind of validation do we want on the runtime side? E.g. throw BadImageFormatException if the length is negative non-positive, or if the struct has multiple fields.

It must be a struct with a single instance field and not having an explicit layout
(I forgot to add the layout part to the proposal, explicit would obviously be in conflict)

I am almost 50%/50% on how we handle nonconforming situations - whether we ignore or throw an exception.
I think loader typically does not throw on misplaced attributes, but could be convinced otherwise.

Is this ok:

 [InlineArray(Length = 10)]
 struct Tenner<T> where T : class {
    public T element0;
 }

How about:

 [InlineArray(Length = 10)]
 struct Tenner<T> {
    public T element0;
 }

Yes.
I do not see anything strange about these. It is basically the target scenario similar to the example given in the proposal.
It may not be interesting to the user to make the field public, but no need to forbid that either.

[tannergooding]

I do not think we have a choice. We cannot remove the field that is already there, thus we cannot follow the directive to have a completely empty array.

Why do you have to remove the field?

The intent behind 0 length fixed sized buffers in C/C++ is:

1. Do not impact sizeof
2. Be a marker field that you can succesfully use for indexing
3. Much like length = 1, support the concept of "variable length inline arrays" and so must be the last field in a struct

We should be able to support and special case both 0 and 1 and have it work as expected both in sizeof calculations and in error handling or type load exceptions if they aren't the last field of a struct.

It must be a struct with a single instance field and not having an explicit layout

I think this is better stated as "must be a sequential layout struct with a single instance field", otherwise that leaves room for interpreting "auto layout" as being ok.

While such encodings are possible, finding one that everybody could comfortably accept has been an issue that we could not resolve.

I do think this is somewhat unfortunate. There are numerous patterns we could allow, particularly in the numerics space (and therefore with opportunities to improve the ecosystem for ML, Tensors, and Vector acceleration) by actually having this.

I thought the idea of using multidimensional array metadata + a special recognized constraint was a clever solution here and would allow this without having to revise IL metadata.

• It's also then not much different from other newer constraints that we support like unmanaged or the possible new self constraint other than it being one the Runtime would enforce/recognize as well.