Value types with custom boxing

[IS4Code]

Motivation

At the moment, Nullable<T> is the only value type that has custom boxing rules, which require the runtime to have hardcoded handling of this type whenever boxing/unboxing occurs. With the recent focus on unions, I think it might be interesting to consider generalizing this special behaviour and extending it to user-defined value types. In practical terms, it means some (specially marked) value types could box/unbox to "arbitrary" objects, even null. With a general mechanism, types mimicking Nullable<T> could be created, and Nullable<T> itself could be expressed in terms of this mechanism.

Situation

At the moment, a simple union of primitive values could be implemented in this compact way:

struct Number
{
    [StructLayout(LayoutKind.Explicit)]
    struct Union
    {
        [FieldOffset(0)]
        public int intValue;
        [FieldOffset(0)]
        public float floatValue;
    }

    int which;
    Union value;
}

New C# syntax or code generators could simplify writing or using such types as needed, but the runtime is still blind to what such a type encodes:

Number n = ...;
object o = n;
Console.WriteLine(o is int); // False
Console.WriteLine(o is float); // False

This could not be fixed in the language alone (like for Nullable<T>), since the boxing may occur in generic types which are blind to the concrete type. In this situation, it might be argued that this is not even desirable, but it only takes a little modification to change that:

struct Number
{
    [StructLayout(LayoutKind.Explicit)]
    struct Union
    {
        [FieldOffset(0)]
        public NumberInt intValue;
        [FieldOffset(0)]
        public NumberFloat floatValue;
    }

    int which;
    Union value;
}

record struct NumberInt(int IntValue);
record struct NumberFloat(float FloatValue);

Now NumberInt and NumberFloat are concrete realizations of Number, conceptually "deriving" from it while adding new members (this is also how tagged union structs might be implemented internally). However, the runtime still cannot see that these new types are special cases of Number:

Number n = ...;
object o = n;
Console.WriteLine(o is NumberInt); // False
Console.WriteLine(o is NumberFloat); // False

There are three options to solve this behaviour:

• Have a runtime-blessed ValueUnion<T...> type which would be boxable to one of its Ts, and any such type would need to be expressed in terms of it. This essentially adds another special type alongside Nullable<T> whereby it can now be conceptualized as ValueUnion<T, null>.
• Have the runtime recognize union structs written in C# and apply the same rules to them. This is better because the language can pick a particular form of the struct that is better (in some terms) than what the runtime, but it requires changing existing custom union types to what C# offers, which might not always be viable.
• Have the runtime provide a mechanism for affecting the boxing/unboxing processing in some way, with a chosen degree of control over it.

The last option is enough to cover most existing cases, and even though it might be very strange to consider now, there were a few situations where something similar has already happened ‒ types like TypedReference got formalized into ref struct, and IDynamicInterfaceCastable was added to affect interface casts in a way only proxying in .NET Framework could do before, so many assumptions about boxing or castability of types got broken a handful of times already.

Implementation

There are two options I can think of to solve this, one more constrained but generally sufficient, and one more powerful but potentially hard to reason about:

Option A ‒ with attributes and fields, safe and predictable

With this approach, a struct may only box to a value of one of the fields it contains (no indirection through references), hereby named the active field. Which field is active is determined by another field storing its identifier. As an example:

[IndirectlyBoxable]
struct Number
{
    [StructLayout(LayoutKind.Explicit)]
    struct Union
    {
        [BoxableField, FieldOffset(0)]
        public NumberInt intValue;
        [BoxableField, FieldOffset(0)]
        public NumberFloat floatValue;
    }

    [BoxedFieldSelector]
    RuntimeFieldHandle which;
    [BoxableFieldsContainer]
    Union value;
}

When such a type is encountered, the runtime has to:

• Determine the set of potential active fields of the type. This is done by navigating through the chain of fields marked with [BoxableFieldsContainer] until none remains, and then getting all fields with [BoxableField] on the last visited type. Additionally, no field marked with [BoxableFieldsContainer] may have a type that is a type parameter. Specified this way, this always results in a single type holding all potentially active fields ‒ the converse would mean potentially having to encode paths to those fields, not just individual fields, in the selector.
• Determine the selector field. This is done through a similar mechanism (navigate through [BoxableFieldsContainer]) but this time, the first type that stores a [BoxedFieldSelector] field is enough (and there must be only one such field). Alternatively, if there is no selector field and there is only one potentially active field, the selector field is implied to always identify that field.
• Ensure that the selector field does not overlap with any potentially active field (or else throw TypeLoadException).

These pieces of information could be stored alongside the type itself in memory. Since no indirection is allowed, a field found in this process can be stored easily as an offset from the beginning of the data alongside the type of the field.

When boxing an instance of a value type marked with [IndirectlyBoxable], the runtime has to:

• Load the value of the selector field (whose location is determined in the previous steps).
• Use the value of the selector field to determine the active field among the set of potential active fields. The possibilities are:
  • As in the example, a RuntimeFieldHandle could be used to identify any field on a type (the one holding the potentially active fields).
  • An integer could be used together with [BoxableField(0)], [BoxableField(1)], etc.
  • If there is only a single potentially active field, bool could be used too (more about this later).
  • If no field is identified in this step (the selector does not contain an identifier of a potentially active field), this results in an InvalidCastException.
• Load and box the value of the active field as if (object)activeField was used.

This indicates recursion during boxing (an [IndirectlyBoxable] type boxing through another [IndirectlyBoxable] type), but that is fine in this case, because it is always bounded by the "depth" of the final (normally boxable) field, since it too must be contained in the original struct's data.

During unboxing, the performed steps are:

• Among the potentially active fields, find any whose type matches the type of the boxed value (more about nulls later). If none is found, the cast fails as usual.
• default-initialize the unboxed type.
• Activate the selected field by assigning the unboxed value to it (bypassing readonly).
• Store the identifier of the field inside the selector field (bypassing readonly).

It is possible (and obvious) that the values of all other fields are not preserved during boxing/unboxing. This is expected and necessary ‒ any important information that needs to be preserved must be stored in the active field.

Handling default/null

An indirectly boxable type could be nullable under one of these conditions:

• It is marked as [IndirectlyBoxable(AllowNull = true)], making it explicitly nullable.
  • This means the value of the selector field may be default. Consequently, no field may be [BoxableField(0)], and the selector field is allowed to be bool.
    • If boxing a value whose selector is default, the boxing results in null.
    • If unboxing null, the result of the unboxing is always simply default of the unboxed-to type.
• Otherwise when at least one of its potentially active fields is nullable (assignable from null), making it implicitly nullable.
  • Boxing this active field results in null.
  • Unboxing null to such a type activates any such nullable potentially active field.

This has these consequences:

• v is null is a sensible condition for a value of such type and is equivalent to (object)v is null.
• Such a type is disallowed as a generic argument to a parameter with the struct constraint (like Nullable<T>).
• A value may box to null from multiple distinguishable states, even when other fields are ignored ‒ the default state for explicitly nullable values, and when the active field boxes to null.
  • The intended reconciliation with this is that it should not matter which state the null comes from. Calling v1.Equals(v2) should result in true when (object)v1 is null and (object)v2 is null (the default implementation should take it into account, and a potential override is responsible for ensuring this).

An indirectly boxable value type whose set of potentially active fields includes a reference-typed field is always nullable.

With these rules, Nullable<T> could be easily expressed as:

[IndirectlyBoxable(AllowNull = true)]
public struct Nullable<T> where T : struct
{
    [BoxedFieldSelector]
    readonly bool hasValue;
    [BoxableField]
    readonly T valueOrDefault;
}

Summary

Pros:

• Both the runtime and the compiler have access to the same information in determining which conversions may succeed and which may not.
  • The compiler can always determine whether a value type is (potentially) nullable by analyzing its potentially active fields (or if AllowNull = true), and may not allow passing the type through the struct constraint if so.
  • The compiler may also use the information to allow (T)v when T is assignable from the type of a potentially active field, equivalent to (T)(object)v, or the converse (converting from a value assignable to one of its potentially active fields).
  • This establishes a sort-of inheritance between value types. The type of a potentially active field is treated as "derived" from the containing indirectly boxable type (a subtype thereof) in many situations.
• There are no additional heap allocations, user code interactions, unexpected exceptions, or any other new situations when converting. Both boxing and unboxing on indirectly boxable types is pretty much a switch to identify the active field, and everything else happens through it.
• Nullable<T> is no longer exceptional in any way and is treated as just a regular explicitly nullable value type.
• A ref struct may be made indirectly boxable when all its potentially active fields are boxable (not non-boxable ref structs).
  • This has potential uses ‒ a ref struct could hold a cached ref struct but be freely boxable through another field whose value could be used, after unboxing, to restore the non-boxable ref struct field.
    • This could be utilized by C# when a ref struct variable crosses async/yield boundary, preserving its state.

Cons:

• Takes a few attributes to express fully.
• The analysis of indirectly boxable types is a bit more involved in order to express the common case (identifying a field from a stored union-typed field).
• When used without restrictions, this approach permits nullable value types other than Nullable<T>. Additional work needs to be done on the compiler's side to ensure those types are not passed through where T : struct, unless the runtime prohibits such nullable types (for the moment).
• If new nullable value types get introduced by this, some preparations of the ecosystem might be needed, for example RuntimeHelpers.Equals should get a generic alternative to avoid (potentially destructive) boxing, and where T : ValueType, new() should be allowed by C# to be able to pick all value types.

Option B ‒ with an interface and no limits

Akin to IDynamicInterfaceCastable, value types could implement a new interface, IDynamicBoxable:

struct Number : IDynamicBoxable<Number>
{
    [StructLayout(LayoutKind.Explicit)]
    struct Union
    {
        [FieldOffset(0)]
        public NumberInt intValue;
        [FieldOffset(0)]
        public NumberFloat floatValue;
    }

    int which;
    Union value;
    
    object IDynamicBoxable<Number>.Box()
    {
        return which switch { 0 => value.intValue, 1 => value.floatValue };
    }
    
    static Number IDynamicBoxable<Number>.Unbox(object obj)
    {
        return obj switch { int i => new Number(i), float f => new Number(f) };
    }
}

The runtime's job is rather simple in this situation ‒ when boxing a value of this type, Box is called; when unboxing to this type, Unbox is called.

Pros:

• Any arbitrary boxing/unboxing rules could be used (covering the previous situations and more).
• Not that big involvement on the runtime's side, just method calling
• The IDynamicBoxable interface could be used/checked manually if needed.

Cons:

• is needs to call Box to determine success (unlike with option A, when knowing the field is enough for most cases).
• Boxing/unboxing may involve arbitrary steps and could affect/block optimizations that were possible before.
• There is no indication of what types the value may be boxed to through the interface alone, and as such reasoning about the result could be more difficult. It is however possible to mandate an attribute that restricts it further:

  [BoxableTo(typeof(NumberInt), typeof(NumberFloat)]
  struct Number : IDynamicBoxable<Number>

  Under such conditions, Box is not allowed to produce any other type than defined here, and returning such would result in InvalidCastException. AllowNull = true could be used here too to arrive at basically the same situation as with option A.

With this option, Nullable<T> can also be expressed:

[BoxableTo(typeof(T), AllowNull = true)]
public struct Nullable<T> : IDynamicBoxable<Nullable<T>> where T : struct
{
    readonly bool hasValue;
    readonly T valueOrDefault;
    
    object IDynamicBoxable<Nullable<T>>.Box()
    {
        return hasValue ? valueOrDefault : null;
    }
    
    static Nullable<T> IDynamicBoxable<Nullable<T>>.Unbox(object obj)
    {
        return obj switch { null => default, T val => new Nullable<T>(val) };
    }
}

[HaloFour]

Boxing is barely the tip of the iceberg when it comes to trying to implement type unions, to the extent that I don't think a container type is reasonable without intimate knowledge and support for it in the runtime. Attempting to emulate "transitivity"/"interchangeability" would be a substantially larger barrier and one that I don't think belongs in the language.

[IS4Code]

That's why I almost made it tangential to the original problem. Also this is why I went with this to the runtime discussions ‒ this is definitely a "runtime hack" along the lines of IDynamicInterfaceCastable, but one that could solve/address at least 3 struct-related issues at once,

C#'s play in this is only to consider using it for compiler-generated unions when applicable, and potentially to recognize such types when doing conversions and generics. And that is not even necessary ‒ if new nullable value types are disallowed for the moment, C# could pretty much ignore this completely without any lesser impact of the feature.

[hez2010]

This is supposed to be a language feature. See https://github.com/dotnet/csharplang/blob/main/proposals/TypeUnions.md#specialized---union-structs
While some runtime help may be needed.

[IS4Code]

Well what I propose is a runtime feature, not a language feature. IDynamicInterfaceCastable is also not a language feature. It should helpful in more cases than just the syntactic sugar C# would provide.

[hez2010]

Yeah, that's why I said "some runtime help may be needed".

[IS4Code]

And? Yes, the language might choose to use the feature I describe, but I don't see how one would come to the conclusion that "customizable boxing rules for structs" is actually a language feature called "specialized union structs". There is even no mention of boxing in what you linked!

This is a runtime feature at the core intended to be usable from all languages, not just C#, hence no reliance on any new syntax. The actual place where a language's involvement is needed is when handling new potentially nullable value types, but C# is not special in that regard ‒ the exact same affects VB.NET and F# alike which need to ensure that such types are not used where not allowed.

Let's please stick to what this idea is actually about.

[hez2010]

Didn't the subsection Boxed Unions mention the exact thing?

This is because the language will not special case the type test when no union struct members are involved, since its not clear which type to check for. Checks for a common union interface could be made to work, but that would unduly impact the vast majority of type tests that do not involve union structs.

"Checks for a common union interface" is exactly a thing like IDynamicBoxable you have proposed, which needs to be handled by the runtime as the C# compiler doesn't know whether the boxed type is a struct union.

[IS4Code]

You are right, I missed that part; I apologize. Yes, the runtime is the best to rely on in that situation (as opposed to checking for an interface during every is and as etc.), but the point of this idea is to solve this generally, outside of just unions. I explicitly disregard this option in one of the first sections:

• Have the runtime recognize union structs written in C# and apply the same rules to them. This is better because the language can pick a particular form of the struct that is better (in some terms) than what the runtime, but it requires changing existing custom union types to what C# offers, which might not always be viable.
• Have the runtime provide a mechanism for affecting the boxing/unboxing processing in some way, with a chosen degree of control over it.

The last option is enough to cover most existing cases, and even though it might be very strange to consider now, there were a few situations where something similar has already happened…

I don't mention or rely on C# in any other parts of the suggestion. This is not about C#. The consequences of this are not just for C#. The usefulness of this is not just for new C# unions.

[timcassell]

It would be nice if it also supports explicit null checks like Nullable<T> has. That way null-coalescing, null-propagating operators could work, and generic null checks would work.

[IS4Code]

That sounds like a good possibility ‒ null checks on unconstrained generic types in C# already result in hidden boxing, so with proper runtime implementation, those should work out of the box. When the type is statically known however, C# would need to recognize it as a nullable value type, and likely box it in the same way to perform the check.