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:368

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:869

Var.fallback_equal

int Var.fallback_equal(Var a, Var b)

Applies non-dispatch equality to a and b.

Source: lib/dispatch.x:719

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:729

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:921

Var.fallback_repr

String Var.fallback_repr(Var v)

Returns the non-dispatch readable representation of Var.

Source: lib/dispatch.x:594

Var.fallback_str

String Var.fallback_str(Var v)

Returns the non-dispatch display String of Var.

Source: lib/dispatch.x:525

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:684

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:562

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:383

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:931

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:432

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:398

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:416

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:581

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:124

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:172

x2c_register_tagged_descriptor

void x2c_register_tagged_descriptor( Symbol tag, String name, VarMethods methods)

Registers an explicitly tagged type or raises <bad-state> if no custom row can be reserved. Tag/name collisions follow the existing fatal descriptor diagnostic; registration still freezes at worker startup.

Source: lib/dispatch.x:203

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:107

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:150

x2c_try_register_tagged_descriptor

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

Reserves custom tag under full 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. Explicit names retain case; ordinary inferred-tag registration still requires lowercase names. Raises: <bad-state> after registration freezes.

Source: lib/dispatch.x:187

RenderPath

RenderPath.enter

int RenderPath.enter(RenderPath *path, const void *identity)

Enters an object’s recursive rendering, or returns zero for a cycle. Keep path alive and defer path.leave() after a successful entry. Identities are compared only along this thread’s active path, so repeated references outside that path render independently. No allocation occurs.

Source: lib/dispatch.x:26

RenderPath.leave

void RenderPath.leave(RenderPath *path)

Restores the path after the most recent successful enter on this thread. Ordinary defer unwinding also restores it when a child renderer raises.

Source: lib/dispatch.x:38

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:890

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:47

Var.equal

int Var.equal(Var a, Var b)

Applies the registered equality operation for a and b.

Source: lib/dispatch.x:762

Var.hash

unsigned Var.hash(Var v)

Returns the runtime hash of Var.

Raises: <void-op> for void.

Source: lib/dispatch.x:738

Var.pointer_string

String Var.pointer_string(Var v)

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

Source: lib/dispatch.x:211

Var.repr

String Var.repr(Var v)

Returns the readable representation of Var.

Source: lib/dispatch.x:605

Var.same

int Var.same(Var a, Var b)

Reports whether a and b have identical Var bits.

Source: lib/dispatch.x:786

Var.str

String Var.str(Var v)

Returns the display String of Var.

Source: lib/dispatch.x:536

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>, <mod>, and <matmul> 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:63

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:88

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:218

Var.write_repr

Buffer Var.write_repr(Var v, Buffer out)

Appends the readable representation of Var to a Buffer.

Source: lib/dispatch.x:697

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:316

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:302

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:310

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:944

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).