lib/dispatch.x

Typed descriptors for runtime Var behavior.

Primary API

Var

Var.contains

meta native 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:591

Var.enumerate

meta native Iter Var.enumerate(Var x, Iter dest)

Returns an iterator over what a two-name foreach destructures. A boxed Map yields (key value) Lists, as Map.enumerate does, and any other value yields what Var.iter yields.

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

Source: lib/dispatch.x:570

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

Var.fallback_equal

int Var.fallback_equal(Var a, Var b)

Applies non-dispatch equality to a and b.

Source: lib/dispatch.x:401

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

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

Var.fallback_repr

String Var.fallback_repr(Var v)

Returns the non-dispatch readable representation of Var.

Source: lib/dispatch.x:188

Var.fallback_str

String Var.fallback_str(Var v)

Returns the non-dispatch display String of Var.

Source: lib/dispatch.x:91

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

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

Var.getindex

meta native 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:606

Var.iter

meta native 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:555

Var.postfixindex

meta native 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:655

Var.setindex

meta native 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:621

Var.updateindex

meta native 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:639

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

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

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

x2c_register_tagged_descriptor

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

Registers an explicitly tagged type or raises <bad-state> for a null tag or name. Tag/name collisions follow the existing fatal descriptor diagnostic; registration still freezes at worker startup.

Source: lib/dispatch.x:860

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. A custom tag spends a Var row only when a value is first boxed. 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:765

x2c_try_register_descriptor

int x2c_try_register_descriptor(String name, VarMethods methods)

Declares a custom Var tag and merges its descriptor callbacks. Returns zero for a null or non-lowercase name, 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:807

x2c_try_register_tagged_descriptor

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

Declares 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 a null tag or name, and one otherwise. A built-in tag or 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:844

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

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

Var

Var.as_string

String Var.as_string(Var v)

Returns what a String destination reads from Var: its String payload, the display String of any other value, or NULL for void and for Null, the null pointer.

Source: lib/dispatch.x:84

Var.compare

meta native int Var.compare(Var a, Var b)

Compares a and b by runtime value group and registered ordering. The order is total, so sorting uses it: numbers order by value, NaN after every other number, and equal values of different types by type. The relational operators compare two numbers as C does instead.

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

Source: lib/dispatch.x:425

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

Var.equal

int Var.equal(Var a, Var b)

Applies the registered equality operation for a and b. Two numbers are equal only with the same tag and the same bits, so this agrees with Var.hash; Map and Pool keys compare this way. The == operator compares two numbers as C does instead.

Source: lib/dispatch.x:378

Var.hash

unsigned Var.hash(Var v)

Returns the runtime hash of Var.

Raises: <void-op> for void.

Source: lib/dispatch.x:339

Var.pointer_string

String Var.pointer_string(Var v)

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

Source: lib/dispatch.x:118

Var.repr

String Var.repr(Var v)

Returns the readable representation of Var.

Source: lib/dispatch.x:180

Var.same

meta native int Var.same(Var a, Var b)

Reports whether a and b have identical Var bits. Two boxes of one wide number differ here, although === holds for them.

Source: lib/dispatch.x:411

Var.str

String Var.str(Var v)

Returns the display String of Var.

Source: lib/dispatch.x:74

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

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

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

Var.write_repr

Buffer Var.write_repr(Var v, Buffer out)

Appends the readable representation of Var to a Buffer.

Source: lib/dispatch.x:204

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

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

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

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

Design notes

A registered type supplies a descriptor of function pointers. Boxed Var operations find the descriptor by tag and call its registered functions; an operation without one uses built-in behavior or raises <no-member>. 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).