Handle Types¶

Overview¶

Handle types reference region-allocated objects. Struct handles are nullable; the compiler tracks whether a handle is known to be non-null at any given point. Slice handles are always valid and cannot be null; a zero-length slice is a valid empty slice that does not allocate memory. The null literal [Point] produces a null struct handle of type &Point.

Syntax¶

// struct handle type
&Point

// slice handle type
[]int

Rules¶

Handle Type¶

The &StructType type MUST represent a struct handle type. & MUST only be applied to struct types. Applying & to a primitive type, capability type, function pointer type, or slice type MUST be a compile-time error. All struct handles are nullable. The compiler MUST track whether a struct handle value is known to be non-null at each point in the program.

The []ElementType type MUST represent a slice handle type. [] MUST only be applied to permitted slice element types.

Handle from Alloc¶

A handle produced by alloc MUST be known to be non-null. The compiler MUST treat such a handle as known-valid without requiring a null check. A zero-length slice produced by alloc MUST still be treated as a valid slice handle.

Handle Validity¶

The read or write operator MUST only be applied to a valid handle. Applying read or write to a struct handle that might be null MUST be a compile-time error. Slice handles are always valid and MUST NOT require a null check. After a move invalidation, the compiler MUST treat a struct handle as null and a slice handle as a zero-length empty slice in all subsequent code paths.

The read or write operator MUST only be applied to a handle that belongs to a region that is still active. Applying read or write to a handle whose source region has been destroyed MUST be a compile-time error.

Handle Nullability¶

A struct handle MUST be convertible to bool where null evaluates to false and non-null evaluates to true. Slice handles MUST NOT be convertible to bool. After a null check, the compiler MUST track the struct handle as known-non-null in code paths where non-nullness is guaranteed.

Struct Handles¶

A struct handle MUST be represented as a 64-bit pointer. The pointer value zero MUST represent null.

Slice Handles¶

Slice handles MUST always be valid. A slice handle MUST NOT be null. A slice with zero length MUST be a valid empty slice that does not allocate memory.

A slice handle MUST be represented as a 128-bit fat pointer { ptr: 64-bit, actual_length: 64-bit }. The actual_length field MUST be checked at runtime before any index access. If the index is out of bounds, the runtime panic function MUST be called. For a zero-length slice, the value of the ptr field is implementation-defined.

Slice Element Types¶

Slice element types MUST include primitive types, function pointer types, struct handles, and slice handles. Slices of capability types (read StructType, write StructType, read []ElementType, write []ElementType) MUST NOT be permitted; capabilities cannot be stored. Raw struct values MUST NOT be permitted as slice elements.