lib/common.x

The Var encoding every runtime module shares.

Advanced and interop API

Functions

x2c_initialize

void x2c_initialize(void)

Initializes the x2c runtime once for the current process.

Source: lib/common.x:845

x2c_initialize_protocols

void x2c_initialize_protocols(void)

Runs compiler-generated runtime protocol registration.

Source: lib/common.x:841

x2c_normalize_index

int x2c_normalize_index(int index, int length)

Normalizes one element index against length.

Source: lib/common.x:871

x2c_normalize_slice

int x2c_normalize_slice(int *start, int *stop, int step, int length)

Normalizes slice bounds and returns the resulting element count.

Source: lib/common.x:896

x2c_slice_bound

int x2c_slice_bound(int bound)

Returns an explicit slice bound that x2c_normalize_slice cannot read as omitted. INT_MIN becomes INT_MIN + 1, which every collection shorter than INT_MAX clamps the same way.

Source: lib/common.x:882

Array

Array.var

inline Var Array.var(Array x)

Boxes an Array value as Var.

Source: lib/common.x:551

Block

Block.var

inline Var Block.var(Block x)

Boxes a Block value as Var.

Source: lib/common.x:553

Buffer

Buffer.var

inline Var Buffer.var(Buffer x)

Boxes a Buffer value as Var.

Source: lib/common.x:555

Bytes

Bytes.var

inline Var Bytes.var(Bytes x)

Boxes a Bytes value as Var.

Source: lib/common.x:557

File

File.var

inline Var File.var(File x)

Boxes a File value as Var.

Source: lib/common.x:562

Iter

Iter.truth

inline int Iter.truth(Iter iter)

Returns nonzero when iter is not null.

Source: lib/common.x:425

Iter.var

inline Var Iter.var(Iter x)

Boxes an Iter value as Var.

Source: lib/common.x:572

List

List.truth

inline int List.truth(List list)

Returns nonzero when list is not nil, the null empty List.

Source: lib/common.x:428

List.var

inline Var List.var(List x)

Boxes a List value as Var.

Source: lib/common.x:559

Map

Map.var

inline Var Map.var(Map x)

Boxes a Map value as Var.

Source: lib/common.x:564

String

String.truth

inline int String.truth(String string)

Returns nonzero when string contains at least one byte. The canonical empty String is null, with no allocated storage.

Source: lib/common.x:432

String.var

inline Var String.var(String x)

Boxes a String value as Var.

Source: lib/common.x:566

Symbol

Symbol.var

inline Var Symbol.var(Symbol x)

Boxes a Symbol value as Var.

Source: lib/common.x:569

Var

Var.array_payload

Array Var.array_payload(Var value)

Extracts the Array payload of value, or NULL for another tag.

Source: lib/common.x:665

Var.block_payload

Block Var.block_payload(Var value)

Extracts the Block payload of value, or NULL for another tag.

Source: lib/common.x:666

Var.box_f32

inline Var Var.box_f32(float value)

Boxes a native float as an immediate <f32> Var.

Source: lib/common.x:533

Var.box_f64

inline Var Var.box_f64(double value)

Boxes a native double as an immediate <f64> Var.

Source: lib/common.x:540

Var.box_i16

Var Var.box_i16(short value)

Boxes a native short as an immediate <i16> Var.

Source: lib/common.x:524

Var.box_i32_bits

Var Var.box_i32_bits(unsigned value)

Boxes an unsigned 32-bit pattern as an immediate <i32> Var.

Source: lib/common.x:528

Var.box_i8

Var Var.box_i8(char value)

Boxes a native char as an immediate <i8> Var.

Source: lib/common.x:520

Var.box_u16

Var Var.box_u16(ushort value)

Boxes a native ushort as an immediate <u16> Var.

Source: lib/common.x:526

Var.box_u32

Var Var.box_u32(unsigned value)

Boxes a native uint as an immediate <u32> Var.

Source: lib/common.x:530

Var.box_u8

Var Var.box_u8(uchar value)

Boxes a native uchar as an immediate <u8> Var.

Source: lib/common.x:522

Var.buffer_payload

Buffer Var.buffer_payload(Var value)

Extracts the Buffer payload of value, or NULL for another tag.

Source: lib/common.x:667

Var.bytes_payload

Bytes Var.bytes_payload(Var value)

Extracts the Bytes payload of value, or NULL for another tag.

Source: lib/common.x:668

Var.char

meta native char Var.char(Var x)

Returns x as a native char under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, out of floating range, or invalidly encoded.

Source: lib/common.x:695

Var.decode_f32

inline float Var.decode_f32(Var value)

Decodes an immediate <f32> Var.

Source: lib/common.x:492

Var.decode_f64

inline double Var.decode_f64(Var value)

Decodes an immediate <f64> Var.

Source: lib/common.x:500

Var.double

meta native double Var.double(Var x)

Returns x as a native double under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, or invalidly encoded.

Source: lib/common.x:824

Var.file_payload

File Var.file_payload(Var value)

Extracts the File payload of value, or NULL for another tag.

Source: lib/common.x:669

Var.float

meta native float Var.float(Var x)

Returns x as a native float under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, or invalidly encoded.

Source: lib/common.x:815

Var.int

int Var.int(Var x)

Returns x as a native int under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, out of floating range, or invalidly encoded.

Source: lib/common.x:731

Var.is_row

inline int Var.is_row( Var value, unsigned top, unsigned long mask, unsigned long bottom)

Reports whether value occupies the encoding row at top/bottom. mask selects the bits the decoder discriminates on within top’s group, so a caller that already knows the row tests it with two compares instead of a decode. var-tags.x projects the rows that qualify; a row whose decoded form carries a validity clause is not one of them and must ask Var.is.

Source: lib/common.x:624

Var.is_wide

inline int Var.is_wide(Var v)

Reports whether v uses a scope-owned wide numeric box.

Source: lib/common.x:483

Var.iter_payload

Iter Var.iter_payload(Var value)

Extracts the Iter payload of value, or NULL for another tag.

Source: lib/common.x:670

Var.list_payload

List Var.list_payload(Var value)

Extracts the List payload of value, or NULL for another tag.

Source: lib/common.x:671

Var.long

meta native long Var.long(Var x)

Returns x as a native long under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, out of floating range, or invalidly encoded.

Source: lib/common.x:758

Var.long_double

meta native long double Var.long_double(Var x)

Returns x as a native long double under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, or invalidly encoded.

Source: lib/common.x:805

Var.long_long

meta native long long Var.long_long(Var x)

Returns x as a native long long under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, out of floating range, or invalidly encoded.

Source: lib/common.x:781

Var.map_payload

Map Var.map_payload(Var value)

Extracts the Map payload of value, or NULL for another tag.

Source: lib/common.x:672

Var.payload32

inline unsigned Var.payload32(Var value)

Returns the low 32 payload bits of an immediate Var.

Source: lib/common.x:489

Var.short

meta native short Var.short(Var x)

Returns x as a native short under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, out of floating range, or invalidly encoded.

Source: lib/common.x:713

Var.string_payload

String Var.string_payload(Var value)

Extracts the String payload of value, or NULL for another tag.

Source: lib/common.x:664

Var.symbol

inline Symbol Var.symbol(Var x)

Extracts the symbol payload after the caller establishes the matching Var kind.

Source: lib/common.x:681

Var.uchar

meta native uchar Var.uchar(Var x)

Returns x as a native uchar under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, out of floating range, or invalidly encoded.

Source: lib/common.x:704

Var.uint

meta native uint Var.uint(Var x)

Returns x as a native uint under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, out of floating range, or invalidly encoded.

Source: lib/common.x:740

Var.ulong

meta native ulong Var.ulong(Var x)

Returns x as a native ulong under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, out of floating range, or invalidly encoded.

Source: lib/common.x:770

Var.ulong_long

meta native unsigned long long Var.ulong_long(Var x)

Returns x as a native unsigned long long under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, out of floating range, or invalidly encoded.

Source: lib/common.x:793

Var.unsigned

meta native unsigned Var.unsigned(Var x)

Returns x as a native unsigned under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, out of floating range, or invalidly encoded.

Source: lib/common.x:749

Var.ushort

meta native ushort Var.ushort(Var x)

Returns x as a native ushort under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, out of floating range, or invalidly encoded.

Source: lib/common.x:722

char

char.repr

String char.repr(char x)

Returns the readable representation of char.

Source: lib/common.x:593

char.str

String char.str(char x)

Returns the display String of char.

Source: lib/common.x:593

char.var

Var char.var(char x)

Boxes a native char value as Var.

Source: lib/common.x:593

double

double.repr

String double.repr(double x)

Returns the readable representation of double.

Source: lib/common.x:602

double.str

String double.str(double x)

Returns the display String of double.

Source: lib/common.x:602

double.var

Var double.var(double x)

Boxes a native double value as Var.

Source: lib/common.x:602

float

float.repr

String float.repr(float x)

Returns the readable representation of float.

Source: lib/common.x:601

float.str

String float.str(float x)

Returns the display String of float.

Source: lib/common.x:601

float.var

Var float.var(float x)

Boxes a native float value as Var.

Source: lib/common.x:601

int

int.repr

String int.repr(int x)

Returns the readable representation of int.

Source: lib/common.x:597

int.str

String int.str(int x)

Returns the display String of int.

Source: lib/common.x:597

int.var

Var int.var(int x)

Boxes a native int value as Var.

Source: lib/common.x:597

long

long.repr

inline String long.repr(long l)

Returns the readable representation of long.

Source: lib/common.x:613

long.str

inline String long.str(long l)

Returns the display String of long.

Source: lib/common.x:611

long.var

inline Var long.var(long x)

Boxes a long value as Var.

Source: lib/common.x:607

short

short.repr

String short.repr(short x)

Returns the readable representation of short.

Source: lib/common.x:595

short.str

String short.str(short x)

Returns the display String of short.

Source: lib/common.x:595

short.var

Var short.var(short x)

Boxes a native short value as Var.

Source: lib/common.x:595

uchar

uchar.repr

String uchar.repr(uchar x)

Returns the readable representation of uchar.

Source: lib/common.x:594

uchar.str

String uchar.str(uchar x)

Returns the display String of uchar.

Source: lib/common.x:594

uchar.var

Var uchar.var(uchar x)

Boxes a native uchar value as Var.

Source: lib/common.x:594

uint

uint.repr

String uint.repr(uint x)

Returns the readable representation of uint.

Source: lib/common.x:598

uint.str

String uint.str(uint x)

Returns the display String of uint.

Source: lib/common.x:598

uint.var

Var uint.var(uint x)

Boxes a native uint value as Var.

Source: lib/common.x:598

ulong

ulong.var

inline Var ulong.var(ulong x)

Boxes a ulong value as Var.

Source: lib/common.x:609

unsigned

unsigned.repr

String unsigned.repr(unsigned x)

Returns the readable representation of unsigned.

Source: lib/common.x:599

unsigned.str

String unsigned.str(unsigned x)

Returns the display String of unsigned.

Source: lib/common.x:599

unsigned.var

Var unsigned.var(unsigned x)

Boxes a native unsigned value as Var.

Source: lib/common.x:599

ushort

ushort.repr

String ushort.repr(ushort x)

Returns the readable representation of ushort.

Source: lib/common.x:596

ushort.str

String ushort.str(ushort x)

Returns the display String of ushort.

Source: lib/common.x:596

ushort.var

Var ushort.var(ushort x)

Boxes a native ushort value as Var.

Source: lib/common.x:596

Runtime-internal callables

These callables connect runtime translation units. They are documented for source readers but are not supported as user API.

Functions

x2c_hash_bytes

inline unsigned x2c_hash_bytes( unsigned long seed, const void *data, size_t width)

Hashes an arbitrary byte block through the shared 64-bit mixer. seed distinguishes callers that hash the same bytes under different types; the byte width distinguishes a final partial word from zero padding.

Source: lib/common.x:462

x2c_hash_word

inline unsigned x2c_hash_word(unsigned long word)

Narrows a mixed word to the nonzero 32-bit hash the tables expect. Zero is reserved to mark an empty bucket, so it maps to all ones.

Source: lib/common.x:452

x2c_mix64

inline unsigned long x2c_mix64(unsigned long word)

Avalanches one 64-bit word. This is MurmurHash3’s fmix64 finalizer, the shared mixer behind every fixed-width hash in the runtime. It is six instructions, and its low bits are as well distributed as its high ones, which is what Map masks. Use x2c_hash_bytes for a block that spans several words.

Source: lib/common.x:440

Public types

Array

typedef Block Array

Scope-owned mutable Block view whose elements are Vars.

Source: lib/common.x:80

Atom

typedef Var Atom

Exact-name Var using a Symbol or a pooled canonical long spelling.

Source: lib/common.x:78

Block

typedef struct Block *Block

Opaque handle to Scope-owned mutable fixed-width storage.

Source: lib/common.x:70

Buffer

typedef struct Buffer *Buffer

Opaque handle to a Scope-owned mutable text builder.

Source: lib/common.x:72

Bytes

typedef void *Bytes

Data pointer into Block-owned raw element storage.

Source: lib/common.x:68

Context

typedef struct Context *Context

Bounded Scope, Error, Match, and optional canonical-pool state.

Source: lib/common.x:92

File

typedef FILE *File

Native stdio stream handle whose opener determines close ownership.

Source: lib/common.x:106

Func

typedef struct Func *Func

Scope-owned generic native-call adapter and optional bound context.

Source: lib/common.x:100

Iter

typedef struct Iter *Iter

Mutable traversal state whose sources must outlive its iteration.

Source: lib/common.x:108

List

typedef struct List *List

Immutable canonical cons chain; NULL is nil. Its lifetime follows its owning List pool, which may be an ancestor.

Source: lib/common.x:84

Map

typedef struct Map *Map

Scope-owned mutable table mapping Var keys to Var values.

Source: lib/common.x:88

Mutex

typedef struct Mutex *Mutex

Scope-owned opaque mutex that must outlive every accessing thread.

Source: lib/common.x:94

Pool

typedef struct Pool *Pool

Nested canonicalization table with Scope-backed object storage.

Source: lib/common.x:90

RenderPath

typedef struct RenderPath { const void *identity; struct RenderPath *previous; } RenderPath

Caller-owned frame in this thread’s active recursive rendering path.

Source: lib/common.x:124

Scope

typedef struct Scope *Scope

Region owner for individually tracked runtime allocations.

Source: lib/common.x:86

String

typedef char *String

Immutable canonical NUL-terminated bytes; NULL is the empty String. Its lifetime follows its owning String pool, which may be an ancestor.

Source: lib/common.x:104

Symbol

typedef unsigned long Symbol

Immediate compact name encoding with no allocation ownership.

Source: lib/common.x:74

SymbolSet

typedef unsigned char *SymbolSet

Borrowed immutable compiler-generated set of compact Symbols.

Source: lib/common.x:76

Thread

typedef struct Thread *Thread

Caller-owned handle to a Context-backed worker. Join the worker before freeing the handle.

Source: lib/common.x:98

Var

typedef union Var { unsigned long u64; double f64, void *p64; } Var

Eight-byte tagged runtime value for immediate scalars and encoded handles. Pointer-bearing values follow the ownership rules of their concrete type; raw Null is all zero bits and void is all one bits.

Source: lib/common.x:27

VarBinaryFn

typedef Var (*VarBinaryFn)(Var lhs, Var rhs)

Applies one descriptor-owned binary operation and returns its result.

Source: lib/common.x:151

VarCompareFn

typedef int (*VarCompareFn)(Var, Var)

Returns negative, zero, or positive for two Vars of one descriptor.

Source: lib/common.x:145

VarContainsFn

typedef int (*VarContainsFn)(Var receiver, Var needle)

Reports whether receiver contains needle.

Source: lib/common.x:149

VarDescriptor

typedef struct VarDescriptor { Symbol tag, int row, value_dispatch; VarMethods methods; String name; } VarDescriptor

Process-global dispatch row for one Var tag, never freed. It borrows native function pointers and the canonical name: callback code must remain loaded, and the name’s owning pool must outlive every later use of the row. A custom descriptor’s row is -1 until its first box assigns one.

Source: lib/common.x:193

VarEqualFn

typedef int (*VarEqualFn)(Var, Var)

Reports value equality for two Vars with the same descriptor.

Source: lib/common.x:139

VarExportContextFn

typedef Var (*VarExportContextFn)(Var value, Context source)

Exports a custom value from source into its destination Context. Implementations move owned storage and recursively export nested values.

Source: lib/common.x:165

VarGetIndexFn

typedef Var (*VarGetIndexFn)(Var receiver, Var key)

Reads one dynamically indexed value.

Source: lib/common.x:155

VarHashFn

typedef unsigned (*VarHashFn)(Var)

Computes one Var hash; Var.hash normalizes a zero result.

Source: lib/common.x:137

VarIterIntoFn

typedef Iter (*VarIterIntoFn)(Var, Iter)

Initializes traversal in caller-provided Iter storage and returns it. The storage and any retained receiver state must outlive traversal.

Source: lib/common.x:143

VarMethods

typedef struct VarMethods { VarStrFn str, repr, VarHashFn hash, VarEqualFn equal, VarCompareFn compare; VarTruthFn truth, VarIterIntoFn iter, VarWriteFn write_str, write_repr; VarContainsFn contains, VarBinaryFn add, sub, mul, div, mod, matmul; VarUnaryFn neg; VarGetIndexFn getindex, VarSetIndexFn setindex, VarUpdateIndexFn updateindex; VarPostfixIndexFn postfixindex, VarExportContextFn export_context; } VarMethods

Sparse process-global callback row for one Var descriptor. Registration stores each non-NULL function pointer without ownership and leaves existing slots unchanged for NULL fields. Callback code must remain loaded until its pointer is replaced or the process ends. Callbacks run synchronously when their operation dispatches; registration invokes none and retains no callback context.

Source: lib/common.x:178

VarPostfixIndexFn

typedef Var (*VarPostfixIndexFn)(Var receiver, Var key, Symbol op)

Applies an indexed postfix operation and returns the prior value.

Source: lib/common.x:161

VarSetIndexFn

typedef Var (*VarSetIndexFn)(Var receiver, Var key, Var value)

Stores an indexed value and returns the assignment result.

Source: lib/common.x:157

VarStrFn

typedef String (*VarStrFn)(Var)

Renders one Var as a display or readable String.

Source: lib/common.x:133

VarTruthFn

typedef int (*VarTruthFn)(Var)

Reports whether a Var is true.

Source: lib/common.x:147

VarUnaryFn

typedef Var (*VarUnaryFn)(Var value)

Applies one descriptor-owned unary operation and returns its result.

Source: lib/common.x:153

VarUpdateIndexFn

typedef Var (*VarUpdateIndexFn)(Var receiver, Var key, Symbol op, Var rhs)

Applies an indexed compound operation and returns the stored result.

Source: lib/common.x:159

VarWriteFn

typedef Buffer (*VarWriteFn)(Var, Buffer)

Appends one Var rendering to a caller-owned Buffer and returns it.

Source: lib/common.x:135

X2CErrorSite

typedef struct X2CErrorSite { const char *file, *function, int line, runtime; } X2CErrorSite

Borrowed source location supplied during one compiler-generated raise. The pointed-to file and function spellings must outlive that call. runtime is set for a site compiled inside the runtime library.

Source: lib/common.x:208

X2CStatic

typedef struct X2CStatic { int ready; void *payload, *owner; struct X2CStatic *next; } X2CStatic

Zero-initialized compiler storage for one dynamic local static. The runtime owns its fields. payload becomes available to the winning initializer before publication; an acquire returning zero observes the committed value. Failed attempts retain their address until teardown. Payload storage retains no referenced runtime objects.

Source: lib/common.x:243

uchar

typedef unsigned char uchar

Unsigned native character type.

Source: lib/common.x:113

uint

typedef unsigned int uint

Unsigned native int type.

Source: lib/common.x:117

ulong

typedef unsigned long ulong

Unsigned native long type.

Source: lib/common.x:119

ushort

typedef unsigned short ushort

Unsigned native short type.

Source: lib/common.x:115

Design notes

Every runtime module includes this one, so it owns what all of them share: the eight-byte Var encoding and its immediate boxing, and the declarations through which modules name each other’s types and operations without an include cycle. Pointer-shaped Var extractors are ABI crossings whose callers establish the source kind; scalar readers convert other numeric tags through Var.convert.