lib/func.x

Generic native function binding.

Advanced and interop API

Functions

x2c_func_reference_argument

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

Returns reference argument i after checking its declared source type. The generated adapter supplies the target pointee type it will cast to. argv must address the prepared argument array and i must be in bounds; compiler-generated adapters establish both facts.

Raises: <bad-types> when the carrier is a value, its address is null, the Func signature and adapter disagree, its type differs, or conversion would discard a qualifier. It does not return on failure.

Source: lib/func.x:225

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.

Source: lib/func.x:167

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, <bad-result> when an adapter returns void, or any cause raised by the adapter or native target. The result has the ownership of the value the adapter returned.

Source: lib/func.x:365

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

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

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

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

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

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; this constructor performs no validation. Compiler-generated adapters use the checked reference reader before calling native code.

Source: lib/func.x:88

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

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_reference_type

List x2c_func_reference_type( Func function, 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:117

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

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 is rejected. Adapters receive no count. Fixed bindings check arity first, and rest bindings receive one packed List argument.

Source: lib/func.x:45

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

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

Design notes

Func binds a synchronous native call. It stores a typed signature and adapter, checks boxed value and typed-reference arguments, and boxes the adapter result. A bound context is copied into the same Scope allocation as the Func.