16Directives and Attributes

Directives are compile-time annotations attached to declarations using ![...] syntax. They modify how the compiler treats the declaration without changing its semantic meaning at the call site.

![inline]
function hot_path(x: int) -> int {
    return x * 2;
}

![repr(packed)]
type struct PackedHeader {
    magic:   u32;
    version: u8;
    flags:   u8;
}

![align(16)]
type struct AlignedData {
    data: f64;
}

16.1 Recognised Attributes#

The test-mode directives (![config(testing)], ![test], ![ignore], ![should_panic]) are documented in the next subsection.

Other names that appear with ![...] syntax are accepted by the parser and recorded so user tooling can observe them, but the compiler emits a warning for any non-builtin name and applies no semantics. A list of reserved-but-unimplemented directive names is in section 21.

16.2 Test Directives#

The test framework introduces a small set of directives recognised by the compiler (section 20 covers usage):

16.3 Memory Layout#

Cryo is a systems language and gives programmers explicit control over the in-memory layout of user-defined types. Layout matters for FFI (matching a struct declared in a C header), for binary protocols (network packets, on-disk records, hardware register maps), and for memory-conscious data structures.

16.3.1 The Default Layout (repr(Cryo))#

Without any explicit directive, a struct has the default Cryo layout:

• Fields are laid out in source order.
• Each field is placed at the lowest offset that satisfies its natural alignment.
• The size of the type is rounded up to the type's alignment (the maximum alignment among its fields, or 1 for empty types).
• Padding bytes inserted to satisfy alignment have undefined content.

The default layout currently matches the platform's C ABI for primitive-typed fields. The language reserves the right to optimise the default layout in future versions (e.g. reordering fields). Do not rely on the default layout for FFI or binary serialisation; use ![repr(C)] for those cases.

16.3.2 ![repr(C)]#

![repr(C)]
type struct timespec {
    tv_sec:  i64;
    tv_nsec: i64;
}

![repr(C)] guarantees that the type's layout matches the platform's C ABI:

• Fields are laid out in source order.
• Padding follows the C rules: each field starts at the lowest offset that is a multiple of its alignment.
• The size of the type is rounded up to the type's alignment.
• The compiler will not reorder fields under any circumstances.

![repr(C)] is the correct choice for any type that is exchanged with C code, mapped to a C header, or used as a binary record. Combine with ![align(N)] to over-align such a struct.

16.3.3 ![repr(packed)]#

![repr(packed)]
type struct PacketHeader {
    version: u8;
    flags:   u8;
    length:  u32;     // no padding before this field
    crc:     u32;
}

![repr(packed)] removes all inter-field padding:

• Fields are laid out in source order.
• Each field is placed at the next byte offset, regardless of its natural alignment.
• The type's alignment is 1.
• The size of the type equals the sum of its fields' sizes.

A repr(packed) type may contain misaligned fields. Taking a Cryo reference (& or mut &) to a field of a repr(packed) type is a compile error: the reference would not be naturally aligned for its referent, which is undefined behaviour. Read or write the field by value instead; the compiler emits the unaligned load/store at the use site.

![repr(packed)] and ![align(N)] are mutually exclusive on the same type.

16.3.4 ![repr(transparent)]#

![repr(transparent)]
type struct Pid {
    inner: i32;
}

![repr(transparent)] declares a wrapper type whose layout is identical to a single contained field:

• The type must have exactly one field whose size is non-zero.
• The wrapper has the same size, alignment, and ABI as that inner field.
• A Pid and an i32 are interchangeable at the ABI level - passing Pid to an extern "C" function is identical to passing i32.

This is the recommended idiom for type-safe wrappers around primitive FFI types (file descriptors, error codes, opaque handles) where the wrapper exists purely for type discipline at the source level.

16.3.5 ![align(N)]#

![align(64)]
type struct CacheLine {
    payload: [u8; 64];
}

![align(N)] sets the minimum alignment of the type to N bytes:

• N must be a power of two between 1 and 65536.
• The actual alignment of the type is max(natural_alignment, N).
• The size of the type is rounded up to its alignment.

![align(N)] is compatible with ![repr(C)] and ![repr(transparent)]; it is mutually exclusive with ![repr(packed)].

![align(N)] on a variable raises that variable's alignment for the lifetime of its storage; this is useful for stack buffers that must satisfy SIMD or hardware-register alignment requirements.

16.3.6 Enums#

A unit enum (no variant payloads) has a discriminant whose type defaults to i32. The discriminant type can be set explicitly with the type-annotation syntax (not a directive):

type enum Color : u8 {
    Red    = 0;
    Green  = 1;
    Blue   = 2;
}

An ADT enum (variants with payloads) is laid out as a tag (i32) followed by a payload area sized to the largest variant, with padding so the payload area is naturally aligned. ![repr(C)] on an ADT enum is reserved syntax and currently produces the same layout as the default.

16.3.7 Inspecting Layout: sizeof(T) and alignof(T)#

sizeof(T) and alignof(T) return compile-time u64 constants reflecting the type's chosen layout - including any ![repr] or ![align] directives applied to it. They are the recommended way to verify FFI struct layout against a C header in a test:

import std::test::assert::{ expect_eq };
import std::test::error::{ TestError };

![test]
function timespec_matches_c() -> Result<(), TestError> {
    expect_eq(sizeof(timespec), 16 as u64)?;
    return expect_eq(alignof(timespec), 8 as u64);
}

function name<T>(param: Type) -> Ret { ... }

function hot_path(x: int) -> int

(parameter) x: int

primitive int

return value;

(parameter) x: int

type struct Name { ... }
type enum Name { ... }
type trait Name { ... }
type union Name { ... }

type struct Name {
    field: Type;
    method(&this) -> Ret { ... }
}

type struct PackedHeader

PackedHeader.magic: u32

primitive u32

PackedHeader.version: u8

primitive u8

PackedHeader.flags: u8

type struct AlignedData

AlignedData.data: f64

primitive f64

type struct timespec

timespec.tv_sec: i64

primitive i64

timespec.tv_nsec: i64

type struct PacketHeader

PacketHeader.version: u8

PacketHeader.flags: u8

PacketHeader.length: u32

PacketHeader.crc: u32

type struct Pid

Pid.inner: i32

primitive i32

type struct CacheLine

CacheLine.payload: [u8; 64]

type enum Name {
    Unit,
    Payload(T),
    Named { x: i32 },
}

type enum Color : u8

Color::Red

Color::Green

Color::Blue

import a::b;
import a::b::{ X, Y };
import a::b as c;
import a::b::*;

namespace std;

namespace std::test;

namespace std::test::assert;

function expect_eq<T>(a: T, b: T) -> Result<(), TestError>
where T: Eq + Display

namespace std::test::error;

type enum TestError {
    Failed(String);
    Other(String);
}

function timespec_matches_c() -> Result<(), TestError>

type enum Result<T, E> {
    Ok(T);
    Err(E);
}

primitive ()

sizeof(T)

type struct timespec

value as Type

primitive u64

value?

alignof(T)

intrinsic function location() -> Location

![arch(x86_64, intel)]
asm {
    mov ${=out}, ${in}
}

&this
mut &this
this

mut &this
mut &Type

const NAME: Type = value;

const x: T

function name(count: i32, args...)

type struct VaArgs {
    ptr: void*;
}

VaArgs::next<T>(&this) -> T
where T: VaArg

const n: i64

namespace app::module;

type struct Pid

extern function exit(code: i32) -> void;
extern "C" {
    function puts(s: string) -> i32;
}

function max<T>(a: T, b: T) -> T
where T: Ord