Module native_bridge

Expand description

The native runtime bridge: the typed helper-call algebra, the exact 32 bamts_* C-ABI helper exports, the panic- and nesting-safe thread-local NativeOps dispatch seam, and the feature-gated JIT and AOT linkage surfaces.

§Where the unsafe lives

Generated CLIF (JIT) and linked object code (AOT) own control flow but call back into this crate for every value/heap/host operation. This module is the only place raw pointers from that generated code are turned into safe Rust:

The exported bamts_* wrappers (bamts_load_constant …) receive raw *mut ShadowFrame / *mut Completion from CLIF, validate them into a safe NativeFrame, and dispatch to the current NativeOps. They never unwind across the C boundary: any panic, missing dispatcher, or invalid frame is turned into a CompletionTag::FatalTrap.
[JitEntry] (feature jit-entry) wraps a finalized cranelift-jit entry-point pointer, bound to its JITModule lifetime.
[linked_program] (feature aot-image) reads the generated external bamts_program_descriptor image.

The helper table below (variant order, symbols, and operand types) is the export contract shared verbatim with bamts_codegen::Helper (crates/bamts-codegen/src/lib.rs, enum Helper / symbol / external_index / param_types). Any drift breaks linkage, so a self-consistent parity test pins it (bamts-codegen depends on this crate under host-jit, so a direct comparison would be a dependency cycle).

Structs§

HelperResult: The outcome of a completion helper: the ABI tag plus the completion value its tag interprets (return value, thrown/yielded handle, or trap id).
LinkedProgram: A validated, borrow-checked view of a linked AOT image. The bytecode is carried opaquely (native code never decodes it); reconstruction/verification is the runtime’s job.
NativeFrame: A validated safe view of a ShadowFrame and its register (handle) array. Constructed only inside the bamts_* wrappers, which reject a null, misaligned, or malformed frame before dispatching.
ProgramDescriptor: The C-layout header of a linked AOT program image, exported by generated code as the external symbol bamts_program_descriptor.
UnitDescriptor: One compiled function in a linked AOT image.

Enums§

AbiError: A typed AOT/entry-linkage failure.
HelperCall: A typed helper invocation. Runtime Values carry their Value type; operator selectors, string-constant ids, function/register indices, and protocol kinds are the raw ABI u32 selectors codegen passes (never
NativeHelper: A runtime helper, identified by its stable ABI index. The variant order is the canonical external_index order (0..31) and is byte-identical to bamts_codegen::Helper; NativeHelper::symbol returns the exact linker symbol generated code resolves against.

Constants§

AOT_ABI_VERSION: The supported AOT image ABI version.
AOT_MAGIC: The little-endian image magic, b"BMTSAOT1".
HELPER_COUNT: The number of runtime helpers, 0..HELPER_COUNT.
TRAP_INVALID_COMPLETION_TAG: out.value id written when a native entry returns an unrecognized completion tag.
TRAP_INVALID_FRAME: out.value id written when a wrapper receives an invalid frame pointer.
TRAP_INVALID_REGISTER: out.value id written when a helper receives an out-of-range register index.
TRAP_MISSING_NATIVE_OPS: out.value id written when a wrapper runs with no installed NativeOps.
TRAP_PANIC: out.value id written when the dispatcher panics (caught at the boundary).

Traits§

NativeEntryTable: A non-self-referential seam for invoking a compiled native entry by its (module_id, function_id) identity. A JIT backend implements this over its JITModule; a linked AOT image (LinkedProgram) implements it over its unit table. The runtime engine stores &dyn NativeEntryTable and routes nested CreateClosure re-entry through it.
NativeOps: The runtime semantic engine the exported helpers dispatch into. Implemented by bamts_runtime’s native engine; installed for the current thread with with_native_ops.

Functions§

bamts_array_extend^⚠: Safety
bamts_array_push^⚠: Safety
bamts_binary^⚠: Safety
bamts_call^⚠: Safety
bamts_construct^⚠: Safety
bamts_consume_fuel^⚠: Safety
bamts_create_array^⚠: Safety
bamts_create_cell^⚠: Safety
bamts_create_closure^⚠: Safety
bamts_create_object^⚠: Safety
bamts_create_private_name^⚠: Safety
bamts_create_regexp^⚠: Safety
bamts_define_accessor^⚠: Safety
bamts_delete_property^⚠: Safety
bamts_export^⚠: Safety
bamts_get_iterator^⚠: Safety
bamts_get_property^⚠: Safety
bamts_import^⚠: Safety
bamts_iterator_next^⚠: Safety
bamts_load_arguments^⚠: Safety
bamts_load_constant^⚠: Safety
bamts_load_global^⚠: Safety
bamts_load_new_target^⚠: Safety
bamts_load_this^⚠: Safety
bamts_object_spread^⚠: Safety
bamts_resume_value^⚠: Safety
bamts_set_property^⚠: Safety
bamts_set_prototype^⚠: Safety
bamts_store_global^⚠: Safety
bamts_truthy^⚠: Safety
bamts_typeof_global^⚠: Safety
bamts_unary^⚠: Safety
with_native_ops: Installs ops as the current thread’s dispatcher for the duration of body, then restores the previous dispatcher.

Type Aliases§

NativeEntryFn: A finalized native entry point: extern "C" fn(frame, out) -> tag.