Copyright	(c) 2026 Tushar Adhatrao
License	MIT
Stability	internal
Safe Haskell	None
Language	GHC2021

WasmEdge.Internal.Ownership

Contents

Owned contexts (Haskell owns, GC finalizes)
Borrowed contexts (no ownership, no finalizer)
Unsafe coercions (internal use only)

Description

This module implements the two fundamental pointer wrappers:

OwnedCtx — Haskell owns the resource; the GC will call the C delete function via a ForeignPtr finalizer if the Haskell object is collected.
BorrowedCtx — Haskell does not own the resource; no finalizer is attached. The lifetime is guaranteed only by the caller.

The phantom type parameter tag prevents mixing up different context types.

Do not import this module in user code.

Synopsis

data OwnedCtx tag = OwnedCtx {
- unOwnedCtx :: !(ForeignPtr tag)
- disarmAction :: !(IO ())
}
mkOwned :: (Ptr tag -> IO ()) -> Ptr tag -> IO (OwnedCtx tag)
withOwned :: OwnedCtx tag -> (Ptr tag -> IO a) -> IO a
touchOwned :: OwnedCtx tag -> IO ()
finalizeOwned :: OwnedCtx tag -> IO ()
disarmOwned :: OwnedCtx tag -> IO ()
newtype BorrowedCtx tag = BorrowedCtx {
- unBorrowedCtx :: Ptr tag
}
borrowCtx :: OwnedCtx tag -> BorrowedCtx tag
withBorrowed :: BorrowedCtx tag -> (Ptr tag -> IO a) -> IO a
unsafeBorrowOwned :: OwnedCtx tag -> BorrowedCtx tag
unsafeOwnedPtr :: OwnedCtx tag -> Ptr tag

Owned contexts (Haskell owns, GC finalizes)

data OwnedCtx tag #

An OwnedCtx tag holds a ForeignPtr with a C delete function attached as a GC finalizer.

The finalizer is called exactly once, either when:

The explicit delete* function is called (via finalizeOwned), or
The ForeignPtr is garbage-collected.

In practice, prefer explicit cleanup with with* bracket functions.

Constructors

OwnedCtx
Fields unOwnedCtx :: !(ForeignPtr tag) disarmAction :: !(IO ())

Instances

Instances details

Eq (OwnedCtx tag) #
Instance details Defined in WasmEdge.Internal.Ownership Methods (==) :: OwnedCtx tag -> OwnedCtx tag -> Bool # (/=) :: OwnedCtx tag -> OwnedCtx tag -> Bool #

mkOwned #

Arguments

:: (Ptr tag -> IO ())	delete / finalize action
-> Ptr tag
-> IO (OwnedCtx tag)

Create an OwnedCtx from a raw Ptr and an IO action to call when the pointer is no longer needed (the delete function).

If the pointer is nullPtr, the delete action is not registered and the resulting OwnedCtx wraps a null foreign pointer.

withOwned :: OwnedCtx tag -> (Ptr tag -> IO a) -> IO a #

Run an IO action with the underlying Ptr of an OwnedCtx. The OwnedCtx is kept alive for the duration of the action.

touchOwned :: OwnedCtx tag -> IO () #

Ensure an OwnedCtx is kept alive up to this point in a sequence of IO actions. Use when passing the underlying pointer to a C function that does not keep a reference, and you need GHC not to collect the object early.

finalizeOwned :: OwnedCtx tag -> IO () #

Explicitly finalize an OwnedCtx, running its cleanup action immediately and disabling future GC finalization.

disarmOwned :: OwnedCtx tag -> IO () #

Disarm the finalizer of an OwnedCtx when ownership has been transferred to a C container (e.g. adding a functiontablememory/global to a ModuleInstance).

Borrowed contexts (no ownership, no finalizer)

newtype BorrowedCtx tag #

A BorrowedCtx tag is a non-owning reference to a C context. It carries no finalizer. The caller must guarantee that the underlying C object outlives any use of this BorrowedCtx.

Constructors

BorrowedCtx
Fields unBorrowedCtx :: Ptr tag

Instances

Instances details

Eq (BorrowedCtx tag) #
Instance details Defined in WasmEdge.Internal.Ownership Methods (==) :: BorrowedCtx tag -> BorrowedCtx tag -> Bool # (/=) :: BorrowedCtx tag -> BorrowedCtx tag -> Bool #

borrowCtx :: OwnedCtx tag -> BorrowedCtx tag #

Borrow an OwnedCtx: extract a non-owning BorrowedCtx. The OwnedCtx must remain alive as long as the BorrowedCtx is used.

withBorrowed :: BorrowedCtx tag -> (Ptr tag -> IO a) -> IO a #

Run an IO action with the underlying Ptr of a BorrowedCtx.

Unsafe coercions (internal use only)

unsafeBorrowOwned :: OwnedCtx tag -> BorrowedCtx tag #

Unsafe: extract a BorrowedCtx from an OwnedCtx without keeping the owner alive. Use only when the caller guarantees lifetime.

unsafeOwnedPtr :: OwnedCtx tag -> Ptr tag #

Unsafe: extract the raw Ptr from an OwnedCtx. The ForeignPtr may be GC'd after this call.