Module callback 

Consumer-implemented callback interfaces: the producer half of the ABI’s vtable contract.

A callback-interface parameter arrives as two slots, a void* ctx the consumer owns and a pointer to a process-wide static vtable. Every vtable starts with the same header (VtableHeader: its size, reserved flags, and the free(ctx) release hook), followed by one extern "C" function pointer per method. The #[weaveffi::module] expansion wraps the pair in a ForeignCallback, implements the producer’s trait on top of it (each method lowers its arguments, calls the vtable entry, adopts the return, then checks out_err), and hands the producer an Arc<dyn Trait>. When the last Arc drops, ForeignCallback calls free(ctx) exactly once.

The producer rejects a vtable whose size is smaller than the vtable it was built with, so a consumer generated from an older contract can’t make the producer call through a slot that doesn’t exist. A larger size is accepted, which lets a newer consumer pass methods this producer doesn’t know yet.

A callback method returns Result<T, ForeignError>. A failure the consumer reports through out_err becomes the Err: a method that throws keeps a declared code of its module’s error domain (decode it with ForeignError::domain), and every other failure has the code FOREIGN_ERROR_CODE.

Structs

ForeignCallback

A consumer-implemented callback interface held by the producer.

ForeignError

A failure a consumer’s callback-interface implementation reported, or a value it returned that the producer couldn’t accept.

VtableHeader

The fixed header every callback-interface vtable starts with, in this order and at these offsets ({prefix}_..._vtable in C).

VtableTooSmall

A vtable’s size is smaller than the vtable the producer was built with.

Traits

CallbackInterface

Ties a callback interface’s dyn Trait to its generated vtable and foreign wrapper.

Vtable

Implemented by every generated #[repr(C)] vtable struct, whose first field is its VtableHeader.

Functions

callback_ret_buffer^⚠

Adopt and decode a value buffer a vtable entry wrote to its out_ptr/out_len slots.

callback_ret_bytes^⚠

Adopt the byte run a vtable entry wrote to its out_ptr/out_len slots.

callback_ret_enum

Lift a C-style enum a vtable entry returned.

callback_ret_object^⚠

Adopt the strong object reference a vtable entry returned.

callback_ret_object_opt^⚠

Adopt the optional object reference a vtable entry returned (I?).

callback_ret_string^⚠

Adopt a string a vtable entry wrote to its out_ptr/out_len slots.

callback_status

Read the out_err slot a vtable entry of a method that doesn’t throw wrote: Ok(()) when the consumer succeeded, otherwise its failure with the code FOREIGN_ERROR_CODE (whatever code it wrote).

callback_status_in

Read the out_err slot a vtable entry of a throws method wrote: a positive code that E declares (with a payload that decodes) is kept, and every other failure gets the code FOREIGN_ERROR_CODE.

lift_callback^⚠

Lift a callback-interface parameter’s (ctx, vtable) slots into the Arc<dyn Trait> the producer’s function takes. name is the parameter’s name, for the error message.

lift_callback_opt^⚠

Lift an optional callback-interface parameter (Cb?): a null vtable is None.