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 Param 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. Steps 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.

• DAG Pipeline — DagStart builds a monomorphized data-flow graph with fan-out and merge. Topology is encoded in the type system — no vtable dispatch, no arena allocation. Dag implements Handler for direct or boxed dispatch. BatchDag owns a pre-allocated input buffer and runs each item through the same DAG independently.

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

• Templates — HandlerTemplate and CallbackTemplate resolve parameters once, then stamp out handlers via generate() by copying pre-resolved state (~1 cycle). Use when handlers are created repeatedly on the hot path (IO re-registration, timer rescheduling).

• 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());

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.

Bevy Analogies

nexus-rt borrows heavily from Bevy ECS’s system model. If you know Bevy, these mappings may help:

nexus-rt	Bevy	Notes
Param	SystemParam	Two-phase init/fetch
Res<T>	Res<T>	Shared resource read
ResMut<T>	ResMut<T>	Exclusive resource write
Local<T>	Local<T>	Per-handler state
Handler<E>	System trait	Object-safe dispatch
IntoHandler	IntoSystem	fn → handler conversion
Plugin	Plugin	Composable registration
World	World	Singletons only (no ECS)
HandlerTemplate	(no equivalent)	Resolve-once, stamp-many

Re-exports

pub use dag::BatchDag;

pub use dag::Dag;

pub use dag::DagStart;

pub use dag::resolve_arm;

pub use pipeline::BatchPipeline;

pub use pipeline::IntoStep;

pub use pipeline::Pipeline;

pub use pipeline::PipelineBuilder;

pub use pipeline::PipelineOutput;

pub use pipeline::PipelineStart;

pub use pipeline::resolve_step;

pub use scheduler::MAX_SYSTEMS;

pub use scheduler::SchedulerInstaller;

pub use scheduler::SchedulerTick;

pub use scheduler::SystemId;

pub use scheduler::SystemScheduler;

pub use shutdown::Shutdown;

pub use shutdown::ShutdownHandle;

pub use system::IntoSystem;

pub use system::System;

pub use system::SystemFn;

pub use template::Blueprint;

pub use template::CallbackBlueprint;

pub use template::CallbackTemplate;

pub use template::HandlerTemplate;

pub use template::TemplatedCallback;

pub use template::TemplatedHandler;

Modules

dag

DAG pipeline — monomorphized data-flow graphs with fan-out and merge.

pipeline

Pre-resolved pipeline dispatch using Param steps.

scheduler

DAG scheduler with boolean propagation.

shutdown

Cooperative shutdown flag for event loops.

system

Reconciliation systems with boolean propagation.

template

Resolve-once, stamp-many handler templates.

testing

Testing utilities for nexus-rt handlers and timer drivers.

Macros

callback_blueprint

Declares a callback CallbackBlueprint key struct.

fan_out

Constructs a FanOut combinator from 2-8 handlers.

handler_blueprint

Declares a handler Blueprint key struct.

Structs

Adapt

Lightweight adapter that decodes a wire-format event into a domain type before dispatching to an inner handler.

Broadcast

Dynamic fan-out combinator. Takes ownership of an event, borrows it, and dispatches &E to N handlers, where N is determined at runtime.

ByRef

Owned-to-reference adapter. Wraps a Handler<&E> and implements Handler<E> — the event is borrowed before dispatch.

Callback

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

CatchAssertUnwindSafe

Panic-catching wrapper for Handler implementations.

Cloned

Reference-to-owned adapter. Wraps a Handler<E> and implements Handler<&E> — the event is cloned before dispatch.

FanOut

Static fan-out combinator. Takes ownership of an event, borrows it, and dispatches &E to N handlers.

Local

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

Owned

Reference-to-owned adapter via ToOwned. Wraps a Handler<E::Owned> and implements Handler<&E> — the event is converted via to_owned() before dispatch.

Registry

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

RegistryRef

Read-only access to the Registry during handler dispatch.

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

Handler

Object-safe dispatch trait for event handlers.

Installer

Install-time trait for event sources.

IntoCallback

Converts a named function into a Callback.

IntoHandler

Converts a plain function into a Handler.

Param

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

Plugin

Composable unit of resource registration.

Type Aliases

HandlerFn

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

Virtual

Type alias for a boxed, type-erased Handler.