Struct HostApi 

#[repr(C)]
pub struct HostApi {

    pub abi_version: u32,
    pub ctx: *mut c_void,
    pub value_kind: extern "C" fn(ctx: *mut c_void, value: GenericValue) -> u32,
    pub bool_get: extern "C" fn(ctx: *mut c_void, value: GenericValue, out: *mut bool) -> bool,
    pub int_get: extern "C" fn(ctx: *mut c_void, value: GenericValue, out: *mut i64) -> bool,
    pub float_get: extern "C" fn(ctx: *mut c_void, value: GenericValue, out: *mut f64) -> bool,
    pub string_get: extern "C" fn(ctx: *mut c_void, value: GenericValue, out: *mut FfiStr) -> bool,
    pub list_len: extern "C" fn(ctx: *mut c_void, value: GenericValue, out: *mut usize) -> bool,
    pub list_get: extern "C" fn(ctx: *mut c_void, value: GenericValue, index: usize) -> FfiReturn,
    pub tuple_len: extern "C" fn(ctx: *mut c_void, value: GenericValue, out: *mut usize) -> bool,
    pub tuple_get: extern "C" fn(ctx: *mut c_void, value: GenericValue, index: usize) -> FfiReturn,
    pub dict_len: extern "C" fn(ctx: *mut c_void, value: GenericValue, out: *mut usize) -> bool,
    pub set_len: extern "C" fn(ctx: *mut c_void, value: GenericValue, out: *mut usize) -> bool,
    pub builtin_get: extern "C" fn(ctx: *mut c_void, name: FfiStr) -> FfiReturn,
    pub is_instance: extern "C" fn(ctx: *mut c_void, value: GenericValue, of_class: GenericValue) -> FfiReturn,
    pub class_of: extern "C" fn(ctx: *mut c_void, value: GenericValue) -> FfiReturn,
    pub attr_get: extern "C" fn(ctx: *mut c_void, receiver: GenericValue, name: FfiStr) -> FfiReturn,
    pub attr_set: extern "C" fn(ctx: *mut c_void, receiver: GenericValue, name: FfiStr, value: GenericValue) -> FfiReturn,
    pub attr_has: extern "C" fn(ctx: *mut c_void, receiver: GenericValue, name: FfiStr) -> FfiReturn,
    pub nil_new: extern "C" fn(ctx: *mut c_void) -> GenericValue,
    pub bool_new: extern "C" fn(ctx: *mut c_void, value: bool) -> GenericValue,
    pub int_new: extern "C" fn(ctx: *mut c_void, value: i64) -> GenericValue,
    pub float_new: extern "C" fn(ctx: *mut c_void, value: f64) -> GenericValue,
    pub string_new: extern "C" fn(ctx: *mut c_void, value: FfiStr) -> FfiReturn,
    pub list_new: extern "C" fn(ctx: *mut c_void) -> GenericValue,
    pub list_push: extern "C" fn(ctx: *mut c_void, list: GenericValue, item: GenericValue) -> FfiReturn,
    pub list_set: extern "C" fn(ctx: *mut c_void, list: GenericValue, index: usize, value: GenericValue) -> FfiReturn,
    pub exception_new: extern "C" fn(ctx: *mut c_void, of_class: GenericValue, message: FfiStr) -> FfiReturn,
    pub value_display: extern "C" fn(ctx: *mut c_void, value: GenericValue) -> GenericValue,
    pub call_value: extern "C" fn(ctx: *mut c_void, callee: GenericValue, args: *const GenericValue, nargs: usize) -> FfiReturn,
    pub invoke_method: extern "C" fn(ctx: *mut c_void, receiver: GenericValue, name: FfiStr, args: *const GenericValue, nargs: usize) -> FfiReturn,
    pub value_str: extern "C" fn(ctx: *mut c_void, value: GenericValue) -> FfiReturn,
    pub dict_get: extern "C" fn(ctx: *mut c_void, dict: GenericValue, key: GenericValue) -> FfiReturn,
    pub dict_set: extern "C" fn(ctx: *mut c_void, dict: GenericValue, key: GenericValue, value: GenericValue) -> FfiReturn,
    pub dict_contains: extern "C" fn(ctx: *mut c_void, dict: GenericValue, key: GenericValue) -> FfiReturn,
    pub set_add: extern "C" fn(ctx: *mut c_void, set: GenericValue, item: GenericValue) -> FfiReturn,
    pub set_contains: extern "C" fn(ctx: *mut c_void, set: GenericValue, item: GenericValue) -> FfiReturn,
    pub value_truthy: extern "C" fn(ctx: *mut c_void, value: GenericValue) -> FfiReturn,
    pub value_equals: extern "C" fn(ctx: *mut c_void, a: GenericValue, b: GenericValue) -> FfiReturn,
    pub value_hash: extern "C" fn(ctx: *mut c_void, value: GenericValue) -> FfiReturn,
    pub root: extern "C" fn(ctx: *mut c_void, value: GenericValue),
    pub unroot: extern "C" fn(ctx: *mut c_void, n: usize),
    pub instance_set_opaque: extern "C" fn(ctx: *mut c_void, receiver: GenericValue, ptr: *mut c_void) -> FfiReturn,
    pub instance_get_opaque: extern "C" fn(ctx: *mut c_void, receiver: GenericValue) -> *mut c_void,
}

The host vtable handed to every plugin call.

ctx is an opaque pointer owned by the host; pass it as the first argument to every callback. Callbacks marked re-entering run generic bytecode, during which garbage collection may occur - see the rooting contract: across a re-entering callback, root every value still held and re-fetch any FfiStr afterward. All other callbacks never trigger collection.

Return conventions, decided solely by whether the payload forces an out-parameter:

• A payload the caller must receive as something other than a GenericValue - a raw machine scalar (bool, i64, f64, usize) or a borrowed FfiStr - cannot ride in an FfiReturn (whose payload is a GenericValue), so it travels through an out-parameter and the callback returns a plain bool - true on success, false on the sole “wrong kind” failure. These carry no exception.
• Everything else - payload is a GenericValue, or there is no payload - returns FfiReturn, carrying a real exception instance on failure whose class and message mirror what the equivalent generic operation would throw.
• Infallible callbacks return their value directly.

Fields

abi_version: u32

ABI version of the host (GENERIC_PLUGIN_ABI_VERSION).

ctx: *mut c_void

Opaque host context; pass it back as the first argument of every callback. Never dereference it.

value_kind: extern "C" fn(ctx: *mut c_void, value: GenericValue) -> u32

Kind of the value, as a ValueKind code.

bool_get: extern "C" fn(ctx: *mut c_void, value: GenericValue, out: *mut bool) -> bool

false if the value is not a bool.

int_get: extern "C" fn(ctx: *mut c_void, value: GenericValue, out: *mut i64) -> bool

Read an integer into out; false if the value is not an integer or does not fit in an i64 (big integers - fall back to value_display).

float_get: extern "C" fn(ctx: *mut c_void, value: GenericValue, out: *mut f64) -> bool

false if the value is not a float.

string_get: extern "C" fn(ctx: *mut c_void, value: GenericValue, out: *mut FfiStr) -> bool

Read the interned bytes of a string value into out (valid until the next re-entering callback); false if the value is not a string.

list_len: extern "C" fn(ctx: *mut c_void, value: GenericValue, out: *mut usize) -> bool

false if the value is not a list.

list_get: extern "C" fn(ctx: *mut c_void, value: GenericValue, index: usize) -> FfiReturn

The element at index. TypeError if the value is not a list; IndexError if the index is out of bounds.

tuple_len: extern "C" fn(ctx: *mut c_void, value: GenericValue, out: *mut usize) -> bool

false if the value is not a tuple.

tuple_get: extern "C" fn(ctx: *mut c_void, value: GenericValue, index: usize) -> FfiReturn

The element at index. TypeError if the value is not a tuple; IndexError if the index is out of bounds.

dict_len: extern "C" fn(ctx: *mut c_void, value: GenericValue, out: *mut usize) -> bool

false if the value is not a dict.

set_len: extern "C" fn(ctx: *mut c_void, value: GenericValue, out: *mut usize) -> bool

false if the value is not a set.

builtin_get: extern "C" fn(ctx: *mut c_void, name: FfiStr) -> FfiReturn

Look up a builtin global by name (exception classes like "TypeError", native classes, builtin functions). NameError if absent; TypeError if the name is invalid UTF-8.

is_instance: extern "C" fn(ctx: *mut c_void, value: GenericValue, of_class: GenericValue) -> FfiReturn

Whether value is an instance of of_class or of a subclass of it (a bool value on success) - the exact semantics of the isinstance builtin, value-type proxy classes included. TypeError if of_class is not a class.

class_of: extern "C" fn(ctx: *mut c_void, value: GenericValue) -> FfiReturn

The class of an instance, as a class value (callable to construct another instance of it - the analogue of type(self)). TypeError if value is not an instance. Lets a plugin method reach its own class from the receiver: e.g. to construct a result of the same class, or to is_instance-check another argument before reading its opaque state.

attr_get: extern "C" fn(ctx: *mut c_void, receiver: GenericValue, name: FfiStr) -> FfiReturn

A field of an instance; AttributeError if absent, TypeError if the receiver is not an instance.

attr_set: extern "C" fn(ctx: *mut c_void, receiver: GenericValue, name: FfiStr, value: GenericValue) -> FfiReturn

Set a field on an instance; TypeError if the receiver is not an instance (the ok value is nil).

attr_has: extern "C" fn(ctx: *mut c_void, receiver: GenericValue, name: FfiStr) -> FfiReturn

Whether an instance has a field (a bool value on success). TypeError if the receiver is not an instance or the name is invalid UTF-8.

nil_new: extern "C" fn(ctx: *mut c_void) -> GenericValue

A new nil value.

bool_new: extern "C" fn(ctx: *mut c_void, value: bool) -> GenericValue

A new bool value.

int_new: extern "C" fn(ctx: *mut c_void, value: i64) -> GenericValue

A new integer value.

float_new: extern "C" fn(ctx: *mut c_void, value: f64) -> GenericValue

A new float value.

string_new: extern "C" fn(ctx: *mut c_void, value: FfiStr) -> FfiReturn

Interns the given UTF-8 bytes into a string value; ValueError on invalid UTF-8.

list_new: extern "C" fn(ctx: *mut c_void) -> GenericValue

A new, empty list.

list_push: extern "C" fn(ctx: *mut c_void, list: GenericValue, item: GenericValue) -> FfiReturn

Append to a list (the ok value is nil); TypeError if the target is not a list.

list_set: extern "C" fn(ctx: *mut c_void, list: GenericValue, index: usize, value: GenericValue) -> FfiReturn

Replace the element at an index (the ok value is nil). TypeError if the target is not a list; IndexError if the index is out of bounds.

exception_new: extern "C" fn(ctx: *mut c_void, of_class: GenericValue, message: FfiStr) -> FfiReturn

A new exception instance of of_class carrying message. TypeError if of_class is not a class deriving from Exception or the message is invalid UTF-8. Sets the message directly, bypassing the class’s __init__ - exactly like the VM’s own throw; use call_value on the class for full construction semantics. Return the instance under FfiStatus::Exception to throw it.

value_display: extern "C" fn(ctx: *mut c_void, value: GenericValue) -> GenericValue

The raw string representation of any value, as a new string value. Does NOT honor a user class’s __str__ (use value_str for that), which makes it safe to call anywhere, including error paths.

call_value: extern "C" fn(ctx: *mut c_void, callee: GenericValue, args: *const GenericValue, nargs: usize) -> FfiReturn

Call a callable value (closure, native, class, …) with the given arguments. Generic exceptions come back as a nonzero status.

invoke_method: extern "C" fn(ctx: *mut c_void, receiver: GenericValue, name: FfiStr, args: *const GenericValue, nargs: usize) -> FfiReturn

Invoke a named method on a receiver.

value_str: extern "C" fn(ctx: *mut c_void, value: GenericValue) -> FfiReturn

String conversion honoring a user class’s __str__.

dict_get: extern "C" fn(ctx: *mut c_void, dict: GenericValue, key: GenericValue) -> FfiReturn

Look up a key (KeyError if absent); re-enters for __hash__/__eq__.

dict_set: extern "C" fn(ctx: *mut c_void, dict: GenericValue, key: GenericValue, value: GenericValue) -> FfiReturn

Insert or replace a key (the ok value is nil).

dict_contains: extern "C" fn(ctx: *mut c_void, dict: GenericValue, key: GenericValue) -> FfiReturn

Whether a dict contains a key (the ok value is a bool).

set_add: extern "C" fn(ctx: *mut c_void, set: GenericValue, item: GenericValue) -> FfiReturn

Add an item to a set (the ok value is nil).

set_contains: extern "C" fn(ctx: *mut c_void, set: GenericValue, item: GenericValue) -> FfiReturn

Whether a set contains an item (the ok value is a bool).

value_truthy: extern "C" fn(ctx: *mut c_void, value: GenericValue) -> FfiReturn

Truthiness honoring __bool__ (the ok value is a bool).

value_equals: extern "C" fn(ctx: *mut c_void, a: GenericValue, b: GenericValue) -> FfiReturn

Equality honoring __eq__ (the ok value is a bool).

value_hash: extern "C" fn(ctx: *mut c_void, value: GenericValue) -> FfiReturn

Hash honoring __hash__ (the ok value is an integer).

root: extern "C" fn(ctx: *mut c_void, value: GenericValue)

Keep a value alive across re-entering callbacks. Roots are released automatically when the plugin function returns; unroot releases the n most recent roots early.

unroot: extern "C" fn(ctx: *mut c_void, n: usize)

Release the n most recently rooted values. Releasing more roots than were pushed corrupts interpreter state.

instance_set_opaque: extern "C" fn(ctx: *mut c_void, receiver: GenericValue, ptr: *mut c_void) -> FfiReturn

Install the plugin’s opaque pointer on a plugin-backed instance (typically from __init__, with the receiver as self). The class’s drop/traverse were declared on its ClassDesc; this only sets the pointer. TypeError if receiver is not a plugin-backed instance.

Overwriting an already-installed pointer leaks the previous one: the host does not run drop on it, since it cannot know whether the plugin still holds a copy elsewhere. To replace state, recover the old pointer with instance_get_opaque and free it yourself first.

instance_get_opaque: extern "C" fn(ctx: *mut c_void, receiver: GenericValue) -> *mut c_void

Recover the pointer installed by HostApi::instance_set_opaque, or null if none was installed (e.g. before __init__ ran) or receiver is not a plugin-backed instance. Never raises.