Crate nexus_rt 

nexus-rt

Runtime primitives for single-threaded, event-driven systems.

nexus-rt provides the building blocks for constructing runtimes where user code runs as handlers dispatched over shared state. It is not an async runtime — there is no task scheduler, no work stealing, no Future polling. Instead, it provides:

• World — World is a unified type-erased singleton store. Each registered type gets a dense index (ResourceId) for ~3-cycle dispatch-time access.

• Resources — Res and ResMut are what users see in handler function signatures. They deref to the inner value transparently.

• Handlers — The SystemParam trait resolves state at build time and produces references at dispatch time. IntoHandler converts plain functions into Handler trait objects for type-erased dispatch.

• Pipeline — PipelineStart begins a typed per-event composition chain. Stages transform data using Option and Result for flow control. Pipeline implements Handler for direct or boxed dispatch. BatchPipeline owns a pre-allocated input buffer and runs each item through the same chain independently — errors on one item don’t affect subsequent items.

• Driver — Driver is the install-time trait for event sources. install() registers resources into WorldBuilder and returns a concrete handle whose poll() method drives the event lifecycle.

• Plugin — Plugin is a composable unit of resource registration. WorldBuilder::install_plugin consumes a plugin to configure state.

Quick Start

use nexus_rt::{WorldBuilder, ResMut, IntoHandler, Handler};

let mut builder = WorldBuilder::new();
builder.register::<u64>(0);
let mut world = builder.build();

fn tick(mut counter: ResMut<u64>, event: u32) {
    *counter += event as u64;
}

let mut handler = tick.into_handler(world.registry_mut());

handler.run(&mut world, 10u32);

assert_eq!(*world.resource::<u64>(), 10);

Safety

The low-level get / get_mut methods on World are unsafe and intended for framework internals. The caller must ensure:

1. The ID was obtained from the same builder that produced the container.
2. The type parameter matches the type registered at that ID.
3. No mutable aliasing — at most one &mut T exists per value at any time.

User-facing APIs (resource, resource_mut, Handler::run) are fully safe.

Re-exports

pub use pipeline::BatchPipeline;

pub use pipeline::IntoStage;

pub use pipeline::Pipeline;

pub use pipeline::PipelineBuilder;

pub use pipeline::PipelineOutput;

pub use pipeline::PipelineStart;

Modules

pipeline

Pre-resolved pipeline dispatch using SystemParam stages.

Structs

Callback

Unified dispatch type. Stores per-callback context alongside pre-resolved resource access.

Local

Per-handler local state. Stored inside the dispatch wrapper (e.g. Callback or pipeline Stage), not in World.

Registry

Type-to-index mapping shared between WorldBuilder and World.

Res

Shared reference to a resource in World.

ResMut

Mutable reference to a resource in World.

ResourceId

Dense index identifying a resource type within a World container.

Sequence

Monotonic event sequence number for change detection.

World

Frozen singleton resource storage.

WorldBuilder

Builder for registering resources before freezing into a World container.

Traits

Driver

Install-time trait for event sources.

Handler

Object-safe dispatch trait for event handlers.

IntoCallback

Converts a named function into a Callback.

IntoHandler

Converts a plain function into a Handler.

Plugin

Composable unit of resource registration.

SystemParam

Trait for types that can be resolved from a Registry at build time and fetched from World at dispatch time.

Type Aliases

HandlerFn

Type alias for context-free handlers (no owned context).

Virtual

Type alias for a boxed, type-erased Handler.