lib/dispatch.x

Typed descriptors for runtime Var behavior.

Primary API

Var

Var.contains

int Var.contains(Var value, Var needle)

Tests dynamic membership through the receiver’s registered protocol row.

Raises: <bad-enc>, <void-op>, or <no-member> when the dynamic receiver cannot perform membership.

Source: lib/dispatch.x:330

Var.fallback_compare

int Var.fallback_compare(Var a, Var b)

Compares without consulting a runtime descriptor.

Raises: <void-op> when either operand is void.

Source: lib/dispatch.x:774

Var.fallback_equal

int Var.fallback_equal(Var a, Var b)

Applies non-dispatch equality to a and b.

Source: lib/dispatch.x:646

Var.fallback_hash

unsigned Var.fallback_hash(Var v)

Returns the non-dispatch runtime hash of Var.

Raises: <void-op> for void.

Source: lib/dispatch.x:656

Var.fallback_iter

Iter Var.fallback_iter(Var x, Iter dest)

Returns a non-dispatch iterator over Var.

Raises: <void-op> for void. A null dest returns NULL without raising.

Source: lib/dispatch.x:826

Var.fallback_repr

String Var.fallback_repr(Var v)

Returns the non-dispatch readable representation of Var.

Source: lib/dispatch.x:571

Var.fallback_str

String Var.fallback_str(Var v)

Returns the non-dispatch display String of Var.

Source: lib/dispatch.x:502

Var.fallback_write_repr

Buffer Var.fallback_write_repr(Var v, Buffer out)

Appends the non-dispatch representation of Var to a Buffer.

Source: lib/dispatch.x:611

Var.fallback_write_str

Buffer Var.fallback_write_str(Var v, Buffer out)

Appends the non-dispatch display text of Var to a Buffer. A primitive, pointer, or void renders straight into out instead of through an intermediate String.

Source: lib/dispatch.x:539

Var.getindex

Var Var.getindex(Var value, Var key)

Reads a dynamic indexed value through the receiver’s protocol row.

Raises: <bad-enc>, <void-op>, or <no-member> when the dynamic receiver cannot be indexed.

Source: lib/dispatch.x:345

Var.iter

Iter Var.iter(Var x, Iter dest)

Returns an iterator over Var.

Raises: <void-op> for void. A null dest returns NULL without raising.

Source: lib/dispatch.x:836

Var.postfixindex

Var Var.postfixindex(Var value, Var key, Symbol op)

Applies a dynamic postfix update at key and returns its prior value.

Raises: <bad-enc>, <void-op>, <no-member>, or a cause from the receiver’s indexed update.

Source: lib/dispatch.x:394

Var.setindex

Var Var.setindex(Var value, Var key, Var replacement)

Stores and returns a dynamic indexed value through its protocol row.

Raises: <bad-enc>, <void-op>, <no-member>, or a cause from the receiver’s indexed assignment.

Source: lib/dispatch.x:360

Var.updateindex

Var Var.updateindex(Var value, Var key, Symbol op, Var rhs)

Applies the registered dynamic compound update at key and returns its result. Mutation and failure behavior belong to that callback; this dispatch adds no thread or failure atomicity guarantee.

Raises: <bad-enc>, <void-op>, <no-member>, or a cause from the receiver’s indexed update.

Source: lib/dispatch.x:378

Var.write_str

Buffer Var.write_str(Var v, Buffer out)

Appends the display text of Var to a Buffer. A descriptor that registers write_str streams straight into out. One that registers only str writes its String through, which materializes the text but keeps existing custom descriptors working. Neither fallback re-enters this function, so a descriptor providing neither cannot recurse.

Source: lib/dispatch.x:558

Advanced and interop API

Functions

x2c_register_builtin_descriptor

int x2c_register_builtin_descriptor(Symbol tag, VarMethods methods)

Merges callbacks into one built-in Var descriptor. Returns zero for a tag without a reserved descriptor and one otherwise. Non-NULL method fields replace their process-global slots; NULL fields preserve installed callbacks, and no callback runs during registration. Function pointers are borrowed, so their code must remain loaded through later dispatch or replacement.

Raises: <bad-state> after descriptor registration is frozen.

Source: lib/dispatch.x:101

x2c_register_descriptor

void x2c_register_descriptor(String name, VarMethods methods)

Attempts to reserve a custom Var tag and merge its descriptor callbacks. This no-result form discards the status from x2c_try_register_descriptor; all registration and freeze behavior is otherwise identical. The name and function pointers are borrowed under the same process-wide lifetime requirements.

Raises: <bad-state> after descriptor registration is frozen, or <alloc-fail> while checking lowercase spelling. Distinct full names that encode one Symbol through _/- folding or truncation abort.

Source: lib/dispatch.x:149

x2c_register_type

void x2c_register_type(String name)

Attempts to make lowercase name available as a process-global Var tag. This no-result form silently ignores invalid names and unavailable custom rows. An active built-in name selects its existing row. The canonical name is borrowed for process-wide collision diagnostics, so its owning pool must outlive later descriptor use.

Raises: <bad-state> after descriptor registration is frozen, or <alloc-fail> while checking lowercase spelling. Distinct full names that encode one Symbol through _/- folding or truncation abort.

Source: lib/dispatch.x:84

x2c_try_register_descriptor

int x2c_try_register_descriptor(String name, VarMethods methods)

Reserves a custom Var tag and merges its descriptor callbacks. Returns zero for a null or non-lowercase name, an unavailable tag, or exhausted custom capacity, and one otherwise. An already active built-in name selects its existing row. Non-NULL fields replace process-global slots; NULL fields preserve installed callbacks. The canonical name and function pointers are borrowed process-wide: the name’s owning pool and callback code must outlive later descriptor use. Registration invokes no callback.

Raises: <bad-state> after descriptor registration is frozen, or <alloc-fail> while checking lowercase spelling. Distinct full names that encode one Symbol through _/- folding or truncation abort.

Source: lib/dispatch.x:127

x2c_try_register_tagged_descriptor

int x2c_try_register_tagged_descriptor( Symbol tag, String name, VarMethods methods)

Reserves custom tag under lowercase type name and merges descriptor callbacks. Unlike x2c_try_register_descriptor, the tag need not be the restricted-Symbol encoding of the name. A built-in tag is rejected so an explicit custom type cannot replace built-in behavior. The name and callbacks have the same process-wide lifetime as ordinary descriptors.

Returns zero for an invalid name, built-in or unavailable tag, or exhausted custom capacity, and one otherwise. Distinct names for one tag abort.

Raises: <bad-state> after registration freezes, or <alloc-fail> while checking lowercase spelling.

Source: lib/dispatch.x:164

Var

Var.compare

int Var.compare(Var a, Var b)

Compares a and b by runtime value group and registered ordering.

Raises: <void-op> when either operand is void.

Source: lib/dispatch.x:795

Var.dispatch_truth

int Var.dispatch_truth(Var value, int *handled)

Tries the registered truth callback for value. A null handled, missing descriptor, or missing callback returns zero. Otherwise handled is set to one and the synchronous callback result is returned; an available handled is cleared before lookup.

Source: lib/dispatch.x:26

Var.equal

int Var.equal(Var a, Var b)

Applies the registered equality operation for a and b.

Source: lib/dispatch.x:677

Var.hash

unsigned Var.hash(Var v)

Returns the runtime hash of Var.

Raises: <void-op> for void.

Source: lib/dispatch.x:665

Var.pointer_string

String Var.pointer_string(Var v)

Formats the fallback display String for a pointer-bearing Var.

Source: lib/dispatch.x:177

Var.repr

String Var.repr(Var v)

Returns the readable representation of Var.

Source: lib/dispatch.x:582

Var.same

int Var.same(Var a, Var b)

Reports whether a and b have identical Var bits.

Source: lib/dispatch.x:691

Var.str

String Var.str(Var v)

Returns the display String of Var.

Source: lib/dispatch.x:513

Var.try_dispatch_binary

int Var.try_dispatch_binary(Var lhs, Symbol member, Var rhs, Var *result)

Tries one registered binary callback for lhs. Only <add>, <sub>, <mul>, <div>, and <mod> select callbacks. Returns one and writes the synchronous callback result when available; otherwise returns zero and leaves result unchanged. A null result returns zero.

Source: lib/dispatch.x:41

Var.try_dispatch_unary

int Var.try_dispatch_unary(Var value, Symbol member, Var *result)

Tries the registered <neg> callback for value. Returns one and writes the synchronous callback result when available; otherwise returns zero and leaves result unchanged. A null result returns zero.

Source: lib/dispatch.x:65

Var.write_pointer_repr

Buffer Var.write_pointer_repr(Var v, Buffer out)

Writes the fallback readable form of a pointer-bearing Var.

Source: lib/dispatch.x:184

Var.write_repr

Buffer Var.write_repr(Var v, Buffer out)

Appends the readable representation of Var to a Buffer.

Source: lib/dispatch.x:624

Runtime-internal callables

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

Functions

x2c_descriptor_registration_frozen

int x2c_descriptor_registration_frozen(void)

Reports under the descriptor lock whether registration is frozen.

Source: lib/dispatch.x:278

x2c_descriptor_thread_start_begin

void x2c_descriptor_thread_start_begin(void)

Locks descriptor registration while a native worker starts. The caller must pair this on the same thread with x2c_descriptor_thread_start_end.

Source: lib/dispatch.x:264

x2c_descriptor_thread_start_end

void x2c_descriptor_thread_start_end(int success)

Ends a native worker start and unlocks descriptor registration. A nonzero success permanently freezes subsequent registration; zero leaves it open for another attempt.

Source: lib/dispatch.x:272

Var

Var.try_export_context

int Var.try_export_context(Var value, Context source, Var *out)

Calls the registered Context exporter for value when one exists. Returns nonzero when the descriptor registers an exporter, and writes its result to out. Context handles built-in value families directly.

Source: lib/dispatch.x:849

Design notes

A registered type supplies a descriptor of function pointers for repr, write, hash, equality, comparison, truthiness, and iteration. Boxed Var operations find the descriptor by tag and call its registered functions. Ordinary method lookup remains static. Equality, identity, and rendering can inspect void. Operations that need an ordinary value, including hashing, ordering, truthiness, and iteration, reject it as an invariant violation.

Tests and examples

make verify (unittest/test-var.x).