Capability Types¶

Overview¶

Capability types provide read or write access to a handle's referent, as opposed to handles which own objects but cannot be directly used to interface with them. Capabilities are obtained via the read and write unary operations on handles. Capability values are copyable aliases intended to be used as local variables and function parameters. Capabilities do not own objects or allocations and therefore cannot be stored in struct members, stored in slice elements, or returned from functions.

Syntax¶

// read struct capability
read Point

// write struct capability
write Point

// read slice capability
read []int

// write slice capability
write []int

Rules¶

Access Modes¶

A read capability MUST provide read-only access to the underlying object. A read capability MUST NOT permit mutation of the underlying object. A write capability MUST provide read-write access to the underlying object.

Capability copies MUST alias the same underlying access rights and MUST NOT transfer ownership or create a distinct borrow.

Capability Types and Operators¶

Capability types (read StructType, write StructType, read []ElementType, write []ElementType) MUST be supported in type positions (such as function parameters). Capability types MUST NOT be formed from primitive types, function pointer types, or raw struct value types. The read and write unary operators (read h, write h) are used to produce capabilities at runtime from handle values.

Storage Prohibition¶

Capabilities MUST NOT be stored as struct members or slice elements.

Return Prohibition¶

Capability types MUST NOT be used as function return types. This applies to both named function declarations and function pointer types.

Representation¶

Struct capabilities (read StructType, write StructType) MUST be represented as 64-bit pointers. Slice capabilities (read []ElementType, write []ElementType) MUST be represented as 128-bit fat pointers { ptr: 64-bit, actual_length: 64-bit }.