NativeLibrary

Module std.abi

import std.abi;

Public declaration contracts and authored examples. A page can document several related symbols. Implementation bodies are excluded.

NativeLibrary

pub final class NativeLibrary<T>
    where T: Movable, MoveAssignable

Owns a primary image, optional companion and complete inline callable table.

Load accepts explicit filesystem paths and publishes no partial table. Compiler-authenticated import modes select one image per slot, with no other image/global fallback. Companion release precedes primary release. Both loader references transfer together during moves. Relative paths resolve against the call's working directory. The owner is noncopyable; moving transfers its loader reference and leaves the source inactive but destructible. Functions borrows readonly inline storage until this owner is moved, assigned or destroyed. Extracted callable values retain no ownership and must not be used after that lifetime. Native invocation is unsafe even though loading, borrowing, moving and destruction are safe.

T: Closed final native table admitted by the compiler, with only public required/optional unsafe C callable import fields. Warning: Loading/release may block and execute native initializers/finalizers. Synchronize management with all calls and image-dependent resources. Releasing a reference does not guarantee physical image unmapping.

Example

module example.native_library;
import std.abi as abi;
from std.prelude import Result;

final class TextApi {
    [abi.Import(Symbol = "strlen", Mode = .RuntimeRequired)]
    pub Length: unsafe fn<.C>(readonly byte*) -> usize;
}

// Safety: Path selects a compatible library implementing C strlen, and the
// call finishes before Library is destroyed. Native initialization belongs
// to the ordinary safe loading boundary.
unsafe fn Measure(Path: str) -> Result<usize, abi.NativeLoadError> {
    let Library = abi.NativeLibrary<TextApi>.Load(Path)?;
    let Functions = Library.Functions();
    unsafe {
        return .Ok { Value = Functions.Length(c"native") };
    }
}

final class CompanionTextApi {
    [abi.Import(Symbol = "strlen", Mode = .RuntimeCompanionRequired)]
    pub Length: unsafe fn<.C>(readonly byte*) -> usize;
}
// Both explicit images must implement C strlen. This illustrates paired
// ownership using two references to the same compatible image, with lookup
// restricted to the companion handle by the authenticated table mode.
unsafe fn MeasureCompanion(Path: str) -> Result<usize, abi.NativeLoadError> {
    let Library = abi.NativeLibrary<CompanionTextApi>.Load(Path, Path)?;
    unsafe { return .Ok { Value = Library.Functions().Length(c"native") }; }
}

fn Main() -> i32 {
    switch abi.NativeLibrary<TextApi>.Load("") {
        case .Ok { Value = Library } => return 1;
        case .Err { Error = Failure } => {
            switch Failure {
                case .InvalidPath => return 0;
                case .OpenFailed => return 2;
                case .RequiredSymbolUnavailable { Field } => return 3;
                case .OutOfMemory => return 4;
            }
        }
    }
}

NativeLibrary.init

pub init(Source: readonly Self&) = delete;

Rejects copying an owning loader reference. Source: Existing owner.

NativeLibrary.init

pub init(Source: mut Self&&)

Transfers the image and inline table into new owner storage. Source: Writable owner left inactive and destructible.

NativeLibrary.operator

pub fn operator =(Source: readonly Self&) -> void = delete;

Rejects copying into a live owner. Source: Existing owner. Return: No value; copying is rejected.

NativeLibrary.operator

pub fn operator =(Source: mut Self&&) -> void

Releases this image and transfers the source owner into its place. Source: Writable owner left inactive and destructible. Return: No value; exact self-move leaves the owner unchanged. Warning: Invalidates existing borrows; dependent work must have finished.

NativeLibrary.Load

pub static fn Load(Path: str) -> Result<NativeLibrary<T>, NativeLoadError>

Loads only the explicit primary image. Path: Nonempty UTF-8 primary filesystem path without embedded NUL. Return: Complete owner/table or recoverable path/open/required-slot/allocation failure. Required companion slots are unavailable; optional companion slots become None without primary fallback. May allocate, block and execute native init.

NativeLibrary.Load

pub static fn Load(Path: str, CompanionPath: str?) -> Result<NativeLibrary<T>, NativeLoadError>

Loads an explicit native path and resolves the complete table. Path: Nonempty UTF-8 primary image path without embedded NUL bytes. CompanionPath: Optional explicit companion path, validated before opening either image. None leaves companion slots absent. Required absent slots fail; optional ones become None. Existing primary slots never retry the companion. Unresolved helper dependencies require explicit native link dependencies; merely loading a local primary does not supply global scope. Return: A sole owning image/table or an owned portable failure category. Warning: May allocate, block and execute native initialization. Required lookup proves resolution; invocation still requires the actual binary signature and behavior to satisfy each unsafe slot contract. Version selects GNU dlvsym lookup, which may return a compatible unversioned definition; it is not proof of exact version metadata.

NativeLibrary.Functions

pub readonly fn Functions() -> readonly T&

Borrows this owner's complete readonly inline callable table. Return: Alias valid until this owner is moved, assigned or destroyed. Warning: Inactive moved-from owners fatal-trap. This borrow retains no image reference and does not authorize unsafe slot invocation.