Struct Nub 

pub struct Nub<P: Personality> { /* private fields */ }

Uniform handle to the nub microkernel substrate, generic over the kernel personality.

Implementations

impl<P: Personality> Nub<P>

pub fn new_local() -> Self

Construct a Nub backed by the personality’s in-process kernel.

pub fn create_hyperlight(path: &str, options: NubOptions) -> Result<Self>

Create a Hyperlight-backed Nub from a guest ELF on disk.

At most one per process. The KVM substrate supports a single live Hyperlight sandbox per process: the guest-VA window is one process-wide fixed reservation, and every sandbox MAP_FIXED-overlays its kernel-shadow at the same VA inside it. A second construction — concurrent or sequential (the guard is never released, even after dropping the first sandbox) — fails loudly with nub_host_kvm::HyperlightError::SandboxAlreadyCreated instead of silently corrupting the live sandbox’s guest memory. Personality entrypoint crates own the blob paths and typically wrap this constructor in a process-wide singleton (e.g. javm::Nub::hyperlight), which reuses the one sandbox across callers.

pub fn state_root(&self) -> CapHash

Current state root.

pub fn evict_jit_all(&self) -> Result<()>

Bench-only: clear the guest’s JIT compile cache so the next invoke_cached pays a full recompile. No-op on the Local backend (which uses the interpreter and has no JIT cache).

pub fn put_object(&self, bytes: &[u8]) -> Result<ObjHash>

Put a personality-encoded object into the active store. The personality decodes, validates, and content-hashes the bytes; the returned ObjHash is the content-addressed key.

pub fn put_object_with_hash( &self, hash: ObjHash, bytes: impl FnOnce() -> Result<Vec<u8>, String>, ) -> Result<()>

Pre-hashed variant. The caller already knows the content hash; on the hot idempotent path this skips encode + hash entirely.

Hyperlight backend: short-circuits on a host-side set of blob hashes this sandbox has already published — on a hit, bytes is never called: no encode, no RPC roundtrip, no guest-side merkle walk (see nub-host-kvm::MultiUseSandbox::put_object_with_hash).

pub fn with_local<R>(&self, f: impl FnOnce(&mut P::Local) -> R) -> Option<R>

Typed escape hatch: run f against the personality’s LocalKernel under the backend lock. Returns None on the Hyperlight backend. Personality entrypoint crates use this to keep their typed publish paths encode-free on Local.

pub fn submit_invoke(&self, request: InvokeRequest) -> Result<InvokeJob>

Submit an invocation and return a job handle. Jobs are queued onto a fixed Nub-owned host executor; Hyperlight execution then runs on the sandbox’s fixed vCPU worker lanes.

pub fn invoke_cached( &self, root: ObjHash, endpoint_idx: u8, args: [u64; 4], initial_gas: u64, ) -> Result<InvocationResult>

Invoke the object graph rooted at a previously-published root hash. V0 args are 4 u64s overlaid per the personality’s register ABI.

Trait Implementations

impl<P: Personality> Clone for Nub<P>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.