Crate twizzler_runtime_api

source ·
Expand description

The Twizzler Runtime API is the core interface definition for Twizzler programs, including startup, execution, and libstd support. It defines a set of traits that, when all implemented, form the full interface that Rust’s libstd expects from a Twizzler runtime.

From a high level, a Twizzler program links against Rust’s libstd and a particular runtime that will support libstd. That runtime must implement the minimum set of interfaces required by the Runtime trait. Libstd then invokes the runtime functions when needed (e.g. allocating memory, exiting a thread, etc.). Other libraries may invoke runtime functions directly as well (bypassing libstd), but note that doing so may not play nicely with libstd’s view of the world.

What does it look like to use the runtime?

When a program (including libstd) wishes to use the runtime, it invokes this library’s get_runtime function, which will return a reference (a &’static dyn reference) to a type that implements the Runtime trait. From there, runtime functions can be called: ``` let runtime = get_runtime(); runtime.get_monotonic()

Note that this function is only exposed if the runtime feature is enabled.


Another library! Right now, Twizzler defines two runtimes: a "minimal" runtime, and a
"reference" runtime. Those are not implemented in this crate. The minimal runtime is implemented
as part of the twizzler-abi crate, as it's the most "baremetal" runtime. The reference runtime
is implemented as a standalone set of crates. Of course, other runtimes can be implemented, as
long as they implement the required interface in this crate, libstd will work.

# Okay but how does get_runtime work?

Well, [get_runtime] is just a wrapper around calling an extern "C" function,
[__twz_get_runtime]. This symbol is external, so not defined in this crate. A crate that
implements [Runtime] then defines [__twz_get_runtime], allowing link-time swapping of runtimes. The twizzler-abi crate defines this symbol with (weak linkage)[https://en.wikipedia.org/wiki/Weak_symbol], causing it to be linked
only if another (strong) definition is not present. Thus, a program can link to a specific
runtime, but it can also be loaded by a dynamic linker and have its runtime selected at load
time.

Modules

  • rt0
    rt0 defines a collection of functions that the basic Rust ABI expects to be defined by some part of the C runtime:

Structs

  • AddrRange
    An address range.
  • BasicAux
    Arguments passed by the runtime to libstd.
  • BasicReturn
    Return value returned by std from LibStdEntry
  • DlPhdrInfo
  • InternalHandleRefs
  • Library
    An abstract representation of a library, useful for debugging and backtracing.
  • LibraryId
    Internal library ID type.
  • MapFlags
    Mapping protections for mapping objects into the address space.
  • ObjID
    An object ID, represented as a transparent wrapper type. Any value where the upper 64 bits are zero is invalid.
  • ObjectHandle
    A handle to an internal object. This has similar semantics to Arc, but since this crate must be #[no_std], we need to implement refcounting ourselves.
  • ThreadSpawnArgs
    Arguments that std expects to pass to spawn.
  • TlsIndex
    An ABI-defined argument passed to __tls_get_addr.

Enums

Traits

Functions

Type Aliases