Sign in

    Milky2018/wasmoon_runtime/native/bridge does not have a README file

    GCHeapHandle

    Managed GC heap handle. Copies retain the heap independently of its owner.

    MemoryDescriptor

    Shared managed linear-memory allocation. Each handle keeps the descriptor and its backing memory alive independently of a Store or JIT context.

    NativeAllocationError

    A native owner could not allocate its backing state.

    NativeCallableRegistry

    Store-local callable identities, built and owned by MoonBit.

    NativeExecutionState

    Store-scoped owner of native invocation lifetimes.

    The active stack models nested native entry. Parked invocations remain in invocations but are absent from active, so any number of component tasks can retain distinct native resources without sharing an execution stack.

    NativeTableHandle

    Managed shared table identity. Native context bindings retain this object.

    CHeapError

    pub(all) suberror CHeapError {
    OutOfBoundsArrayAccess
    NullReference
    OutOfMemory
    }

    CHeap error types for runtime errors

    CHeap

    pub struct CHeap {
    // private fields
    } derive(
    Debug
    )

    Logical owner of a shared managed GC heap.

    CHeap::CHeap

    fn CHeap::CHeap(capacity? : Int) -> CHeap raise CHeapError

    Create a new C heap with the given initial capacity

    CHeap::alloc_array

    fn CHeap::alloc_array(self : CHeap, type_idx : Int, len : Int, init_value :
    Value
    ) -> Int raise CHeapError

    Allocate a new array with initial value Returns gc_ref (0-based index for external use)

    CHeap::alloc_array_from_values

    fn CHeap::alloc_array_from_values(self : CHeap, type_idx : Int, elements : Array[
    Value
    ]) -> Int raise CHeapError

    Allocate a new array from existing values Returns gc_ref (0-based index for external use)

    CHeap::alloc_struct

    fn CHeap::alloc_struct(self : CHeap, type_idx : Int, fields : Array[
    Value
    ]) -> Int raise CHeapError

    Allocate a new struct Returns gc_ref (0-based index for external use)

    CHeap::array_copy

    fn CHeap::array_copy(self : CHeap, dst_idx : Int, dst_offset : Int, src_idx : Int, src_offset : Int, count : Int) -> Unit raise CHeapError

    Copy array elements

    CHeap::array_fill

    fn CHeap::array_fill(self : CHeap, array_idx : Int, offset : Int, value :
    Value
    , count : Int) -> Unit raise CHeapError

    Fill array elements with a value

    CHeap::array_get

    fn CHeap::array_get(self : CHeap, array_idx : Int, elem_idx : Int, elem_type :
    ValueType
    ) ->
    Value
    raise CHeapError

    Get an array element

    CHeap::array_len

    fn CHeap::array_len(self : CHeap, array_idx : Int) -> Int

    Get array length

    CHeap::array_set

    fn CHeap::array_set(self : CHeap, array_idx : Int, elem_idx : Int, value :
    Value
    ) -> Unit raise CHeapError

    Set an array element

    CHeap::bind_root_visitor

    fn CHeap::bind_root_visitor(self : CHeap, visitor : (Int, FixedArray[Int64]) -> FixedArray[Int64]) -> Unit

    Supply a transitive typed root set before collection (phase 0), and release unreachable auxiliary handles after sweep (phase 1). Bind outside execution.

    CHeap::clear_root_visitor

    fn CHeap::clear_root_visitor(self : CHeap) -> Unit

    Release a scoped embedding visitor after execution or collection completes.

    CHeap::collect

    fn CHeap::collect(self : CHeap, roots : Array[
    Value
    ]) -> Int

    Perform garbage collection with given roots Returns the number of objects collected

    CHeap::collect_raw

    fn CHeap::collect_raw(self : CHeap, roots : Array[Int64]) -> Int

    Complete native root words, including tagged exception snapshots.

    CHeap::free

    fn CHeap::free(self : CHeap) -> Unit

    Close this owner. Other managed handles, contexts and root leases stay live.

    CHeap::get_barrier_writes

    fn CHeap::get_barrier_writes(self : CHeap) -> Int

    Get total number of write-barrier calls recorded

    CHeap::get_base

    fn CHeap::get_base(self : CHeap) -> Int64

    Get heap base pointer (for JIT inline access)

    CHeap::get_capacity

    fn CHeap::get_capacity(self : CHeap) -> Int64

    Get heap capacity (total allocated bytes)

    CHeap::get_kind

    fn CHeap::get_kind(self : CHeap, idx : Int) -> Int

    Get the kind of an object (1=struct, 2=array)

    CHeap::get_object_count

    fn CHeap::get_object_count(self : CHeap) -> Int

    Get number of objects in heap

    CHeap::get_offset

    fn CHeap::get_offset(self : CHeap, idx : Int) -> Int

    Get object offset in heap (for JIT inline access)

    CHeap::get_ptr

    Retain the managed C heap for JIT or exception use.

    CHeap::get_size

    fn CHeap::get_size(self : CHeap) -> Int64

    Get current heap size (bytes used)

    CHeap::get_total_allocations

    fn CHeap::get_total_allocations(self : CHeap) -> Int

    Get total number of allocations since heap creation

    CHeap::get_total_collections

    fn CHeap::get_total_collections(self : CHeap) -> Int

    Get total number of GC cycles performed

    CHeap::get_type_idx

    fn CHeap::get_type_idx(self : CHeap, idx : Int) -> Int

    Get the type index of an object

    CHeap::get_usage_ratio

    fn CHeap::get_usage_ratio(self : CHeap) -> Double

    Get heap usage ratio (0.0 to 1.0)

    CHeap::is_array

    fn CHeap::is_array(self : CHeap, idx : Int) -> Bool

    Check if this is an array

    CHeap::is_struct

    fn CHeap::is_struct(self : CHeap, idx : Int) -> Bool

    Check if this is a struct

    CHeap::is_valid

    fn CHeap::is_valid(self : CHeap, idx : Int) -> Bool

    Check if an object reference is valid

    CHeap::make_allocation_rollback

    fn CHeap::make_allocation_rollback(self : CHeap, roots : () -> Array[
    Value
    ]) -> (() -> Unit)

    Return an owner-bound action that reclaims later allocations unless they remain reachable when the action runs. Retained object-table indices are never reused.

    CHeap::reference_candidates

    fn CHeap::reference_candidates(self : CHeap, index : Int) -> FixedArray[Int64]

    Low words for conservative tracing of allocations without a declared type.

    CHeap::runtime_type

    fn CHeap::runtime_type(self : CHeap, index : Int) -> Int

    CHeap::set_runtime_type

    fn CHeap::set_runtime_type(self : CHeap, index : Int, identity : Int) -> Unit

    CHeap::should_collect

    fn CHeap::should_collect(self : CHeap, threshold? : Double) -> Bool

    Check if GC should be triggered based on heap usage Default threshold is 75% of capacity

    CHeap::struct_get

    fn CHeap::struct_get(self : CHeap, struct_idx : Int, field_idx : Int, field_type :
    ValueType
    ) ->
    Value

    Get a struct field value

    CHeap::struct_set

    fn CHeap::struct_set(self : CHeap, struct_idx : Int, field_idx : Int, value :
    Value
    ) -> Unit

    Set a struct field value

    CHeap::to_repr

    CHeap::verify

    fn CHeap::verify(self : CHeap, verbose? : Bool) -> Bool

    Verify heap invariants (for debugging)

    GcSlot

    pub struct GcSlot {
    lo : Int64
    hi : Int64
    } derive(Eq,
    Debug
    )

    One field or element as the C heap stores it.

    lo is the runtime word. Every value kind except v128 is encoded entirely into it, and it is the only word the collector scans for references, so a reference must never be written to hi.

    GcSlot::equal

    fn GcSlot::equal(GcSlot, GcSlot) -> Bool

    GcSlot::not_equal

    fn GcSlot::not_equal(x : GcSlot, y : GcSlot) -> Bool

    GcSlot::to_repr

    JITTable

    Shared indirect table that can be used by multiple JIT modules.

    JITTable::get_entry_type

    fn JITTable::get_entry_type(self : JITTable, table_idx : Int) -> Int

    Read raw entry type index from the shared table.

    JITTable::get_entry_value

    fn JITTable::get_entry_value(self : JITTable, table_idx : Int) -> Int64

    Read raw entry value bits from the shared table.

    JITTable::get_max

    fn JITTable::get_max(self : JITTable) -> Int64?

    Get the table max size.

    JITTable::get_size

    fn JITTable::get_size(self : JITTable) -> Int

    Get the table size.

    JITTable::raw_ptr

    Retain the stable managed table descriptor.

    JITTable::refresh_layout

    fn JITTable::refresh_layout(self : JITTable, table_ptr :
    NativeTableHandle
    , size : Int) -> Unit

    Refresh table pointer and size from its registered JIT context view.

    JITTable::set

    fn JITTable::set(self : JITTable, table_idx : Int, func_ptr : Int64, type_hash : Int) -> Unit

    Set an entry in the shared table.

    JITTable::to_repr

    JITTableOwner

    type JITTableOwner derive(
    Debug
    )

    Logical close capability for one shared JIT table view.

    JITTableOwner::close

    fn JITTableOwner::close(self : JITTableOwner) -> Unit

    Close all aliases of this view and release its reference. Context bindings and independently retained handles remain live. Repeated close is harmless.

    JITTableOwner::table

    fn JITTableOwner::table(self : JITTableOwner) -> JITTable

    Borrow the table without transferring its destruction capability.

    JITTableOwner::try_alloc

    fn JITTableOwner::try_alloc(size : Int, max : Int64?) -> JITTableOwner?

    Create a new owned shared JIT table. Note: size 0 is valid (empty table that can grow later).

    MemoryInfo

    pub struct MemoryInfo {
    ptr :
    MemoryDescriptor

    size : Int64
    max_pages : Int?
    }

    Memory information for JIT execution.

    MemoryInfo::MemoryInfo

    Create a new MemoryInfo.

    NativeAtomicWait

    pub type NativeAtomicWait

    Owns one native wait registration, including its memory descriptor lease. Dropping the object cancels its registration; explicit cancellation is idempotent. Creation requires a checked, aligned shared-memory address.

    NativeAtomicWait::cancel

    fn NativeAtomicWait::cancel(self : NativeAtomicWait) -> Unit

    NativeAtomicWait::pause

    fn NativeAtomicWait::pause(self : NativeAtomicWait) -> Unit

    Request a one-millisecond sleep when the registration is still pending. Cooperative schedulers use poll instead.

    NativeAtomicWait::poll

    fn NativeAtomicWait::poll(self : NativeAtomicWait) -> Int

    Returns -1 while pending, or the Wasm wait result 0/1/2. After cancellation returns 3. Polling never blocks the embedding thread.

    EXCEPTION_REF_TAG

    let EXCEPTION_REF_TAG : Int64

    Native exception handles have their own tag, distinct from odd i31 words.

    alloc_guarded_memory_desc

    fn alloc_guarded_memory_desc(initial_pages : Int, max_pages : Int?, is_shared? : Bool) ->
    MemoryDescriptor

    Allocate a guarded (reserved) memory descriptor for memory32 memory0. This is required for bounds-check elimination; out-of-bounds accesses trap via guard pages.

    alloc_memory

    fn alloc_memory(size : Int64) -> Int64

    Allocate unmanaged storage for native ABI fixtures (returns 0 on failure). The caller owns its bounds and must free it exactly once. Use descriptors for linear-memory access through checked operations.

    alloc_memory_desc

    fn alloc_memory_desc(size_bytes : Int64, max_pages : Int64?, is_memory64? : Bool, page_size_log2? : Int, is_shared? : Bool) ->
    MemoryDescriptor

    Allocate a wasmoon_memory_t descriptor with owned backing memory.

    atomic_fence

    fn atomic_fence() -> Unit

    atomic_notify

    fn atomic_notify(descriptor :
    MemoryDescriptor
    , offset : Int64, count : Int) -> Int

    atomic_wait_begin

    fn atomic_wait_begin(descriptor :
    MemoryDescriptor
    , offset : Int64, width : Int, expected : Int64, timeout : Int64) -> NativeAtomicWait?

    borrow_table

    Retain a checked native table view without exposing its internal fields.

    cooperative_idle

    fn cooperative_idle() -> Unit

    Briefly sleep an idle cooperative scheduler while only waits remain.

    decode_externref

    fn decode_externref(raw : Int64) -> Int?

    decode_funcref_idx

    fn decode_funcref_idx(raw : Int64) -> Int?

    decode_gc_heap_ref

    fn decode_gc_heap_ref(raw : Int64) -> Int?

    decode_heap_ref

    fn decode_heap_ref(encoded : Int64) -> Int

    Decode a heap reference from JIT representation Returns 0-based heap_idx for MoonBit Store/CHeap

    decode_store_funcref

    fn decode_store_funcref(raw : Int64) -> Int?

    encode_exception_ref

    fn encode_exception_ref(index : Int) -> Int64

    encode_externref

    fn encode_externref(host_idx : Int) -> Int64

    encode_funcref_idx

    fn encode_funcref_idx(func_idx : Int) -> Int64

    encode_gc_heap_ref

    fn encode_gc_heap_ref(heap_idx0 : Int) -> Int64

    encode_null_ref

    fn encode_null_ref() -> Int64

    encode_store_funcref

    fn encode_store_funcref(address : Int) -> Int64

    Stable Store function identity; executable registration is independent.

    free_memory

    fn free_memory(mem_ptr : Int64) -> Unit

    Release an unmanaged allocation returned by alloc_memory. The caller must ensure no aliases remain and must not pass a descriptor backing address.

    gc_debug_set_fail_alloc

    fn gc_debug_set_fail_alloc(fail_at : Int, fail_every? : Int) -> Unit

    Configure allocation fault injection for debugging

    i64_to_value

    Decode a runtime word to a Value based on expected type.

    A word carries no high half, so a V128 request yields a vector whose upper 8 bytes are zero. Callers reading a stored field want slot_to_value, which has the other half.

    is_exception_ref

    fn is_exception_ref(raw : Int64) -> Bool

    is_funcref_ptr

    fn is_funcref_ptr(raw : Int64) -> Bool

    is_null_ref

    fn is_null_ref(raw : Int64) -> Bool

    memory_atomic_compare_exchange

    fn memory_atomic_compare_exchange(descriptor :
    MemoryDescriptor
    , offset : Int64, width : Int, expected : Int64, replacement : Int64) -> Int64

    memory_atomic_load

    fn memory_atomic_load(descriptor :
    MemoryDescriptor
    , offset : Int64, width : Int) -> Int64

    The descriptor must remain live; its offset, width and alignment must have been checked by the linear-memory owner before entering these primitives.

    memory_atomic_rmw

    fn memory_atomic_rmw(descriptor :
    MemoryDescriptor
    , offset : Int64, width : Int, operation : Int, value : Int64) -> Int64

    memory_atomic_store

    fn memory_atomic_store(descriptor :
    MemoryDescriptor
    , offset : Int64, width : Int, value : Int64) -> Unit

    memory_descriptor_copy

    fn memory_descriptor_copy(destination_memory :
    MemoryDescriptor
    , destination : Int64, source_memory :
    MemoryDescriptor
    , source : Int64, length : Int64) -> Int

    Copy checked byte ranges between live memory descriptors.

    memory_descriptor_fill

    fn memory_descriptor_fill(mem_desc_ptr :
    MemoryDescriptor
    , destination : Int64, value : Int, size : Int) -> Int

    memory_descriptor_fill64

    fn memory_descriptor_fill64(memory :
    MemoryDescriptor
    , destination : Int64, value : Int, length : Int64) -> Int

    Fill a checked byte range of a live memory descriptor.

    memory_descriptor_grow

    fn memory_descriptor_grow(mem_desc_ptr :
    MemoryDescriptor
    , delta_pages : Int, max_pages : Int) -> Int

    memory_descriptor_grow64

    fn memory_descriptor_grow64(mem_desc_ptr :
    MemoryDescriptor
    , delta_pages : Int64) -> Int64

    memory_descriptor_length

    fn memory_descriptor_length(mem_desc_ptr :
    MemoryDescriptor
    ) -> Int64

    memory_descriptor_move

    fn memory_descriptor_move(mem_desc_ptr :
    MemoryDescriptor
    , destination : Int64, source : Int64, size : Int) -> Int

    memory_descriptor_read

    fn memory_descriptor_read(mem_desc_ptr :
    MemoryDescriptor
    , offset : Int64, out : FixedArray[Byte], size : Int) -> Int

    Return 0 on success, -1 for an invalid descriptor, memory range or destination buffer length. Rejected operations leave the destination unchanged.

    memory_descriptor_write

    fn memory_descriptor_write(mem_desc_ptr :
    MemoryDescriptor
    , offset : Int64, data : FixedArray[Byte], size : Int) -> Int

    Return 0 on success, -1 for an invalid descriptor, memory range or source buffer length. Rejected operations leave the destination unchanged.

    memory_descriptor_write_bytes

    fn memory_descriptor_write_bytes(mem_desc_ptr :
    MemoryDescriptor
    , offset : Int64, data : Bytes, size : Int) -> Int

    Return 0 on success, -1 for an invalid descriptor, memory range or source buffer length. Rejected operations leave the destination unchanged. Return 0 on success, -1 for an invalid descriptor, memory range or source buffer length. Rejected operations leave the destination unchanged.

    slot_to_value

    Decode a C heap slot to a Value based on expected type.

    Total, and inverse to value_to_slot: every ValueType names a value this can produce, so no case has to fall back to a value of some other type the way V128 => I64(raw) once did.

    supported

    fn supported() -> Bool

    tag_funcref_ptr

    fn tag_funcref_ptr(func_ptr : Int64) -> Int64

    untag_funcref_ptr

    fn untag_funcref_ptr(tagged_ptr : Int64) -> Int64

    value_to_i64

    fn value_to_i64(value :
    Value
    ) -> Int64

    Encode a Value as a bare runtime word, for the root array the collector scans. A root's high word would never be read, so dropping it is not a loss of information here.

    value_to_slot

    fn value_to_slot(value :
    Value
    ) -> GcSlot

    Encode a Value into a C heap slot.

    Total, and that is the point: a slot is 16 bytes, so there is no value this cannot represent and no case left to abort on.

    Encoding rules for lo:
    • i32: sign-extended to i64
    • i64: as-is
    • f32: lower 32 bits (IEEE 754 bits)
    • f64: as-is (IEEE 754 bits)
    • v128: low 8 bytes, with the high 8 in hi
    • structref/arrayref: (gc_ref) << 1, where gc_ref = idx + 1 (even, low bit = 0)
    • funcref: tagged Store function identity (0 = null)
    • externref: extern index + 1 (0 = null)
    • exnref: exception index + 1 (0 = null)
    • i31: (value << 1) | 1 (tagged, low bit = 1)
    • null: 0

    GC reference detection in gc_heap_mark uses: (lo & 1) == 0 && lo > 0