lib/func.x

Generic native function binding.

Advanced and interop API

Functions

x2c_func_pointer_argument

void *x2c_func_pointer_argument(Func fn, const FuncArg *argv, unsigned i)

Returns the address value argument i carries. Generated adapters use it for a pointer parameter with no Var tag of its own, such as const char * or struct timespec *, and for a record passed by value, whose bytes the adapter copies. Any pointer, reference, or String argument is accepted, as C converts it to the parameter’s pointer type.

Raises: <bad-types> for any other argument.

Source: lib/func.x:249

x2c_func_record_result

Var x2c_func_record_result(const void *bytes, size_t size)

Boxes a record result as a <p48> to a copy of its size bytes in the active Scope.

Source: lib/func.x:271

x2c_func_reference_argument

void *x2c_func_reference_argument( Func fn, const FuncArg *argv, unsigned i, List want)

Checks a reference argument whose stored pointee matches want exactly.

Raises: <bad-types> on the same mismatches as the shared checker.

Source: lib/func.x:278

x2c_func_value_argument

Var x2c_func_value_argument( Func fn, const FuncArg *argv, unsigned i, Symbol want)

Checks and converts value argument i, reporting its position. Generated adapters call this once per value parameter before unboxing, so a reference carrier or wrong tag is refused before reaching native code. argv must address the prepared argument array and i must be in bounds; compiler-generated adapters establish both facts.

Raises: <void-op> for a void argument, <bad-types> when an object or Symbol argument does not carry want or the carrier holds a reference, and <alloc-fail>, <bad-enc>, <bad-target>, <conv-range>, or <no-convert> from a numeric conversion. The result has tag want. A detail names the argument’s tag, since any tag may arrive here and an identity-bearing detail value terminates at the error floor before it reaches the handler that would report it.

Source: lib/func.x:215

Func

Func.apply

Var Func.apply(Func f, unsigned argc, const FuncArg *argv)

Invokes a bound native function synchronously and returns its boxed result. argv is borrowed only for the call. Value bits are passed by value; reference arguments alias their caller-owned targets and may be mutated. A rest binding first interns one List containing the value arguments in their original order; rest arguments must not be void, since Lists exclude void from their element domain.

Raises: <bad-arg> for a null binding or argument storage, <bad-arity> for the wrong argument count, <void-op>, <bad-types>, <bad-enc>, <bad-target>, <no-convert>, or <conv-range> while converting an argument, <alloc-fail> or <size-limit> while packing rest arguments, or any cause raised by the adapter or native target. A void adapter result remains no-value. Other results have the ownership of the value the adapter returned.

Source: lib/func.x:106

Func.apply_value

inline Var Func.apply_value(Func fn, Var value)

Applies fn to one argument passed by value. value travels as FuncArg.value carries it, so a callback with a reference parameter raises <bad-types>. Returns, owns, and raises as Func.apply does.

Source: lib/func.x:149

Func.apply_values

inline Var Func.apply_values(Func fn, Var left, Var right)

Applies fn to two arguments passed by value, left then right. Each travels as Func.apply_value carries its argument. Returns, owns, and raises as Func.apply does.

Source: lib/func.x:158

Func.context

const void *Func.context(Func function)

Returns borrowed read-only access to a Func’s copied context. The pointer remains valid only for the Func’s Scope lifetime and is NULL when the binding has no context.

Raises: <bad-arg> for a null binding. It does not return on failure.

Source: lib/func.x:443

Func.new

Func Func.new(FuncAdapter adapter, List signature)

Builds a fixed-arity native-function binding in the current Scope. A direct function expression is compiler-adapted; an expression already typed FuncAdapter is stored as supplied. The canonical signature and adapter code are borrowed for the Func lifetime. Only the signature’s outer shape is checked here, so a hand-written adapter must agree with its parameter count and types.

Raises: <bad-sig> for a null adapter or a malformed signature, and <alloc-fail> when binding storage cannot be allocated.

Source: lib/func.x:351

Func.new_context

Func Func.new_context( FuncAdapter adapter, List signature, const void *context, size_t context_size)

Builds a fixed-arity binding with copied context in the current Scope. The max_align_t-aligned bytes share the Func allocation. The byte copy is shallow: changing the source bytes does not change the binding, while any pointers inside them keep their original targets and lifetimes. A zero size may use NULL storage. The canonical signature and adapter code are borrowed for the Func lifetime.

Raises: <bad-arg> when a nonzero size has no source, <size-limit> when the allocation size overflows, <bad-sig> for a null adapter or malformed signature, or <alloc-fail> when storage cannot be allocated. None return.

Source: lib/func.x:378

Func.new_rest

Func Func.new_rest(FuncAdapter adapter, List signature)

Builds a native-function binding that takes any number of value arguments. The signature declares one List parameter, and the adapter receives every argument in order through that List. Func.apply enforces no arity and conses the arguments itself. Use this for a variadic operation; a fixed one belongs in Func.new, which is faster and reports a wrong count. The canonical signature and adapter code are borrowed for the Func lifetime. The result belongs to the current Scope.

Raises: <bad-sig> for a null adapter, a malformed signature, or a signature whose parameters are anything but one List, and <alloc-fail> when binding storage cannot be allocated.

Source: lib/func.x:365

Func.var

Var Func.var(Func function)

Boxes function without copying or retaining the Func. The returned Var carries the same pointer and shares its Scope lifetime.

Source: lib/func.x:462

FuncArg

FuncArg.reference

inline FuncArg FuncArg.reference(const void *reference, List type)

Constructs a Func argument borrowing a typed lvalue address. The address and canonical type must remain valid through Func.apply; an optional reference may use a null address. This constructor performs no validation. Compiler-generated adapters use the checked reference reader before calling native code.

Source: lib/func.x:141

FuncArg.value

inline FuncArg FuncArg.value(Var value)

Constructs a Func argument by copying one Var value. Pointer-bearing payload storage is not copied or retained and must outlive the call that consumes the argument.

Source: lib/func.x:133

Var

Var.func

Func Var.func(Var v)

Returns the borrowed native callable carried by v.

Raises: <bad-types> when the value is not a Func.

Source: lib/func.x:466

Runtime-internal callables

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

Functions

x2c_func_declared_reference_argument

void *x2c_func_declared_reference_argument( Func fn, const FuncArg *argv, unsigned i, List declared_target, List want)

Checks a generated adapter’s declared pointee against the stored signature and its resolved want against the source address before casting.

Raises: <bad-types> on either mismatch.

Source: lib/func.x:285

x2c_func_reference_type

List x2c_func_reference_type(Func fn, unsigned argc, unsigned index)

Returns the borrowed pointee type for reference parameter index. A value or rest parameter returns NULL. Generated direct calls query it before evaluating the source argument, so an output-only lvalue is not read.

Raises: <bad-arg> for a null Func or an index outside argc, or <bad-arity> when argc disagrees with a fixed signature.

Source: lib/func.x:179

x2c_func_shared

Func x2c_func_shared(FuncAdapter adapter, List signature)

Builds the shared handle for a direct function or noncapturing lambda. The compiler stores the result in a file-static Func that every conversion of that function reuses, so the binding lives for the program and Func.move never transfers it.

Raises: the causes of Func.new.

Source: lib/func.x:389

x2c_func_unrepresentable_argument

FuncArg x2c_func_unrepresentable_argument(Func fn, unsigned i, List source)

Rejects a value argument whose source type has no Var representation. Generated calls use this branch instead of compiling an impossible conversion. Raises: <bad-types>.

Source: lib/func.x:264

Func

Func.move

void Func.move(Func function, Scope *slot)

Transfers function’s storage to the Scope held by slot. The shared handle of a direct function or noncapturing lambda lives for the program and stays where it is, so a caller may hand any Func to an operation that takes ownership. A NULL function does nothing.

Raises: the causes of Scope.move, which leave ownership unchanged.

Source: lib/func.x:454

Func.signature

List Func.signature(Func function)

Returns a native binding’s borrowed canonical signature. The result has the ((func (PARAMETERS...)) RESULT...) shape supplied to the constructor and remains valid for the binding’s lifetime.

Source: lib/func.x:433

Public types

FuncAdapter

typedef Var (*FuncAdapter)(Func fn, const FuncArg *argv)

Uniform shape of a native Func adapter. A Func stores the callback pointer without retaining it and calls it synchronously with borrowed fn and argv; the callback code must outlive the Func. Compiler-generated adapters use the checked value and reference readers, call their native target, and box its result. A returned void remains no-value. Adapters receive no count. Fixed bindings check arity first, and rest bindings receive one packed List argument.

Source: lib/func.x:48

FuncArg

typedef struct FuncArg { FuncArgData data; List reference_type; } FuncArg

Argument carrier borrowed for one synchronous Func.apply call. A null reference_type selects the copied Var bits; otherwise reference and the canonical source type are borrowed and must remain valid through the call. A reference target may be mutated by the native function.

Source: lib/func.x:35

FuncArgData

typedef union FuncArgData { Var value; const void *reference; } FuncArgData

Storage for either the value or reference member selected by FuncArg. Pointer-bearing Var storage and referenced objects belong to the caller.

Source: lib/func.x:24

Design notes

Func owns the binding of one synchronous native call: a canonical signature, an adapter, and optional context bytes copied into the same Scope allocation. Arguments reach native code only through the checked value and reference readers that generated adapters call.