Struct World 

pub struct World { /* private fields */ }

Frozen singleton resource storage.

Created by WorldBuilder::build(). Resources are indexed by dense ResourceId for O(1) dispatch-time access (~3 cycles per fetch).

Safe API

• resource / resource_mut — cold-path access via HashMap lookup.

Unsafe API (framework internals)

The low-level get / get_mut methods are unsafe — used by SystemParam::fetch for ~3-cycle dispatch. The caller must ensure no mutable aliasing.

Implementations

impl World

pub fn builder() -> WorldBuilder

Convenience constructor — returns a new WorldBuilder.

pub fn registry(&self) -> &Registry

Returns a shared reference to the type registry.

Use this for read-only queries (e.g. id, contains). For construction-time calls like into_system, use registry_mut instead.

pub fn registry_mut(&mut self) -> &mut Registry

Returns a mutable reference to the type registry.

Needed at construction time for into_system, into_callback, and into_stage which call Registry::check_access.

Examples found in repository

examples/optional_resources.rs (line 84)

fn main() {
    println!("=== Scenario 1: All optional resources present ===\n");
    {
        let mut builder = WorldBuilder::new();
        builder
            .register(Config { threshold: 5.0 })
            .register(DebugLog {
                entries: Vec::new(),
            })
            .register(Metrics {
                events_processed: 0,
            });
        let mut world = builder.build();

        let mut process = process_event.into_handler(world.registry_mut());
        let mut track = track_metrics.into_handler(world.registry_mut());

        for value in [3.0, 7.5, 1.2] {
            process.run(&mut world, value);
            track.run(&mut world, value);
            println!();
        }

        let log = world.resource::<DebugLog>();
        println!("Debug log entries: {:?}", log.entries);

        let metrics = world.resource::<Metrics>();
        println!("Events processed: {}", metrics.events_processed);
    }

    println!("\n=== Scenario 2: No optional resources ===\n");
    {
        let mut builder = WorldBuilder::new();
        builder.register(Config { threshold: 5.0 });
        // DebugLog and Metrics intentionally not registered.
        let mut world = builder.build();

        let mut process = process_event.into_handler(world.registry_mut());
        let mut track = track_metrics.into_handler(world.registry_mut());

        for value in [3.0, 7.5] {
            process.run(&mut world, value);
            track.run(&mut world, value);
            println!();
        }

        println!("Handlers ran cleanly without optional resources.");
    }

    println!("\nDone.");
}

examples/perf_construction.rs (line 142)

fn main() {
    // Register enough types to exercise the check_access bitset.
    let mut wb = WorldBuilder::new();
    wb.register::<u64>(0);
    wb.register::<u32>(0);
    wb.register::<bool>(false);
    wb.register::<f64>(0.0);
    wb.register::<i64>(0);
    wb.register::<i32>(0);
    wb.register::<u8>(0);
    wb.register::<u16>(0);
    let mut world = wb.build();
    let r = world.registry_mut();

    print_header("into_handler Construction (cycles)");

    bench_batched("into_handler  1-param (Res<u64>)", || {
        let _ = black_box(sys_1p.into_handler(r));
        0
    });

    bench_batched("into_handler  2-param (Res + ResMut)", || {
        let _ = black_box(sys_2p.into_handler(r));
        0
    });

    bench_batched("into_handler  4-param", || {
        let _ = black_box(sys_4p.into_handler(r));
        0
    });

    bench_batched("into_handler  8-param", || {
        let _ = black_box(sys_8p.into_handler(r));
        0
    });

    bench_batched("into_handler  2-param (Local + ResMut)", || {
        let _ = black_box(sys_local.into_handler(r));
        0
    });

    bench_batched("into_handler  2-param (Option<Res> + ResMut)", || {
        let _ = black_box(sys_option.into_handler(r));
        0
    });

    println!();
    print_header("into_callback Construction (cycles)");

    bench_batched("into_callback 2-param (Res + ResMut)", || {
        let _ = black_box(cb_2p.into_callback(0u64, r));
        0
    });

    bench_batched("into_callback 4-param", || {
        let _ = black_box(cb_4p.into_callback(0u64, r));
        0
    });

    println!();
    print_header("into_stage Construction (cycles)");

    bench_batched(".stage() 2-param (Res + ResMut)", || {
        let _ = black_box(PipelineStart::<u32>::new().stage(stage_2p, r));
        0
    });

    bench_batched(".stage() 4-param", || {
        let _ = black_box(PipelineStart::<u32>::new().stage(stage_4p, r));
        0
    });

    println!();
}

examples/local_state.rs (line 55)

fn main() {
    println!("=== Example 1: Simple counter ===\n");
    {
        let mut world = WorldBuilder::new().build();
        let mut sys = counting_handler.into_handler(world.registry_mut());

        sys.run(&mut world, "alpha");
        sys.run(&mut world, "beta");
        sys.run(&mut world, "gamma");
    }

    println!("\n=== Example 2: Independent instances ===\n");
    {
        let mut builder = WorldBuilder::new();
        builder.register::<i64>(0);
        let mut world = builder.build();

        // Two handlers from the same function — each has its own Local<i64>.
        let mut sys_a = accumulator.into_handler(world.registry_mut());
        let mut sys_b = accumulator.into_handler(world.registry_mut());

        println!("sys_a gets 10:");
        sys_a.run(&mut world, 10i64);

        println!("sys_b gets 20:");
        sys_b.run(&mut world, 20i64);

        println!("sys_a gets 5:");
        sys_a.run(&mut world, 5i64);

        // sys_a local: 15, sys_b local: 20, world total: 35
        println!("\nWorld total: {}", world.resource::<i64>());
        assert_eq!(*world.resource::<i64>(), 35);
    }

    println!("\n=== Example 3: Batch buffer ===\n");
    {
        let mut builder = WorldBuilder::new();
        builder.register::<Vec<u32>>(Vec::new());
        let mut world = builder.build();

        let mut sys = batch_writer.into_handler(world.registry_mut());

        // First two events accumulate locally.
        sys.run(&mut world, 1u32);
        println!("  output len: {}", world.resource::<Vec<u32>>().len());

        sys.run(&mut world, 2u32);
        println!("  output len: {}", world.resource::<Vec<u32>>().len());

        // Third event triggers flush.
        sys.run(&mut world, 3u32);
        println!("  output len: {}", world.resource::<Vec<u32>>().len());

        // Fourth event starts a new batch.
        sys.run(&mut world, 4u32);
        println!("  output len: {}", world.resource::<Vec<u32>>().len());

        let output = world.resource::<Vec<u32>>();
        println!("\nFinal output: {:?}", &*output);
        assert_eq!(&*output, &[1, 2, 3]);
    }

    println!("\nDone.");
}

examples/pipeline.rs (line 86)

fn main() {
    // --- Bare value pipeline: arity-0 closure stages ---

    println!("=== Bare Value Pipeline ===\n");

    let mut world = WorldBuilder::new().build();
    let r = world.registry_mut();

    let mut bare_pipeline = PipelineStart::<u32>::new()
        .stage(|x: u32| x * 2, r)
        .stage(|x: u32| x + 1, r);

    println!("  5 → {}", bare_pipeline.run(&mut world, 5));
    println!("  10 → {}", bare_pipeline.run(&mut world, 10));

    // --- Option pipeline: filter + inspect (cold path), map (hot path) ---

    println!("\n=== Option Pipeline ===\n");

    let mut wb = WorldBuilder::new();
    wb.register(PriceCache::new());
    let mut world = wb.build();
    let r = world.registry_mut();

    let mut option_pipeline = PipelineStart::<MarketTick>::new()
        .stage(
            |tick: MarketTick| -> Option<MarketTick> {
                if tick.price > 0.0 { Some(tick) } else { None }
            },
            r,
        )
        .filter(|_w, tick| tick.symbol == "BTC")
        .inspect(|_w, tick| {
            println!("  [inspect] {} @ {:.2}", tick.symbol, tick.price);
        })
        .map(store_price, r);

    let ticks = [
        MarketTick {
            symbol: "BTC",
            price: 50_000.0,
        },
        MarketTick {
            symbol: "ETH",
            price: 3_000.0,
        }, // filtered: not BTC
        MarketTick {
            symbol: "BTC",
            price: -1.0,
        }, // filtered: negative
        MarketTick {
            symbol: "BTC",
            price: 51_000.0,
        },
    ];

    for tick in ticks {
        option_pipeline.run(&mut world, tick);
    }

    let cache = world.resource::<PriceCache>();
    println!(
        "\n  PriceCache: latest={:.2}, updates={}",
        cache.latest, cache.updates
    );
    assert_eq!(cache.updates, 2);
    assert_eq!(cache.latest, 51_000.0);

    // --- Result pipeline: validate → check → catch → store ---

    println!("\n=== Result Pipeline with catch ===\n");

    let mut wb = WorldBuilder::new();
    wb.register(PriceCache::new());
    wb.register::<u64>(0); // error counter
    let mut world = wb.build();
    let r = world.registry_mut();

    let mut result_pipeline = PipelineStart::<MarketTick>::new()
        .stage(validate, r)
        .and_then(check_known, r)
        .catch(count_error, r)
        .map(store_price, r);

    let ticks = [
        MarketTick {
            symbol: "BTC",
            price: 52_000.0,
        },
        MarketTick {
            symbol: "XYZ",
            price: 100.0,
        }, // unknown symbol → catch
        MarketTick {
            symbol: "ETH",
            price: -5.0,
        }, // invalid price → catch
        MarketTick {
            symbol: "ETH",
            price: 3_500.0,
        },
    ];

    for tick in ticks {
        result_pipeline.run(&mut world, tick);
    }

    let errors = *world.resource::<u64>();
    println!("\n  Errors: {errors}");
    assert_eq!(errors, 2);

    // --- Build into Handler ---

    println!("\n=== Pipeline as Handler ===\n");

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

    let mut pipeline = PipelineStart::<u32>::new().stage(accumulate, r).build();

    pipeline.run(&mut world, 10);
    pipeline.run(&mut world, 20);
    pipeline.run(&mut world, 30);

    let total = *world.resource::<u64>();
    println!("  Total: {total}");
    assert_eq!(total, 60);

    println!("\nDone.");
}

examples/mock_runtime.rs (line 218)

fn main() {
    // -- Build ----------------------------------------------------------------

    let mut wb = WorldBuilder::new();
    wb.install_plugin(TradingPlugin {
        initial_prices: vec![("BTC", 50_000.0), ("ETH", 3_000.0)],
        risk_cap: 100,
    });
    let mut md = wb.install_driver(MarketDataInstaller);
    let mut world = wb.build();

    // Standalone handler — demonstrates change detection.
    fn on_signal(signals: Res<SignalBuffer>, _event: ()) {
        black_box(signals.signals.len());
    }
    let mut signal_handler = on_signal.into_handler(world.registry_mut());

    // -- Correctness check ----------------------------------------------------

    let ticks = [
        MarketTick {
            symbol: "BTC",
            price: 50_100.0,
        }, // delta=100 > 50 → signal
        MarketTick {
            symbol: "ETH",
            price: 3_010.0,
        }, // delta=10 < 50 → no signal
        MarketTick {
            symbol: "BTC",
            price: 49_900.0,
        }, // delta=200 > 50 → signal
    ];

    md.poll(&mut world, &ticks);

    // 2 signals accepted, risk cap=100 so both go through.
    assert_eq!(world.resource::<OrderCount>().0, 2);

    // Change detection: SignalBuffer was modified → handler should run.
    assert!(signal_handler.inputs_changed(&world));
    signal_handler.run(&mut world, ());

    // Advance sequence, no new writes → handler should skip.
    world.next_sequence();
    assert!(!signal_handler.inputs_changed(&world));

    println!("Correctness checks passed.\n");

    // -- Latency measurement --------------------------------------------------

    const WARMUP: usize = 1_000;
    const ITERATIONS: usize = 1_000;

    // Ticks that exercise the full pipeline path (signal detection + cache write).
    let bench_ticks = [
        MarketTick {
            symbol: "BTC",
            price: 50_100.0,
        },
        MarketTick {
            symbol: "ETH",
            price: 3_100.0,
        },
        MarketTick {
            symbol: "BTC",
            price: 50_200.0,
        },
        MarketTick {
            symbol: "ETH",
            price: 3_200.0,
        },
    ];

    println!(
        "=== nexus-rt Dispatch Latency (cycles, {} iterations) ===\n",
        ITERATIONS
    );
    println!(
        "{:<44} {:>8} {:>8} {:>8}",
        "Operation", "p50", "p99", "p999"
    );
    println!("{}", "-".repeat(72));

    // Single tick through dyn pipeline
    {
        let tick = bench_ticks[0];
        for _ in 0..WARMUP {
            world.next_sequence();
            md.pipeline.run(&mut world, black_box(tick));
        }
        let mut samples = Vec::with_capacity(ITERATIONS);
        for _ in 0..ITERATIONS {
            world.next_sequence();
            let start = rdtsc_start();
            md.pipeline.run(&mut world, black_box(tick));
            let end = rdtsc_end();
            samples.push(end.wrapping_sub(start));
        }
        report("single tick (dyn pipeline, 3 stages)", &mut samples);
    }

    // Standalone handler (1 param, Res<T>)
    {
        for _ in 0..WARMUP {
            black_box(());
            signal_handler.run(&mut world, ());
        }
        let mut samples = Vec::with_capacity(ITERATIONS);
        for _ in 0..ITERATIONS {
            let start = rdtsc_start();
            black_box(());
            signal_handler.run(&mut world, ());
            let end = rdtsc_end();
            samples.push(end.wrapping_sub(start));
        }
        report("handler dispatch (1 param, Res<T>)", &mut samples);
    }

    // 4-tick batch through driver poll
    {
        for _ in 0..WARMUP {
            md.poll(&mut world, &bench_ticks);
        }
        let mut samples = Vec::with_capacity(ITERATIONS);
        for _ in 0..ITERATIONS {
            let start = rdtsc_start();
            md.poll(&mut world, black_box(&bench_ticks));
            let end = rdtsc_end();
            samples.push(end.wrapping_sub(start));
        }
        let mut per_tick: Vec<u64> = samples
            .iter()
            .map(|&s| s / bench_ticks.len() as u64)
            .collect();
        report("4-tick poll (total)", &mut samples);
        report("4-tick poll (per tick)", &mut per_tick);
    }

    // Change detection
    {
        world.next_sequence(); // ensure stale
        for _ in 0..WARMUP {
            black_box(signal_handler.inputs_changed(&world));
        }
        let mut samples = Vec::with_capacity(ITERATIONS);
        for _ in 0..ITERATIONS {
            let start = rdtsc_start();
            black_box(signal_handler.inputs_changed(&world));
            let end = rdtsc_end();
            samples.push(end.wrapping_sub(start));
        }
        report("inputs_changed (1 param, stale)", &mut samples);
    }

    println!();
}

examples/perf_pipeline.rs (line 241)

fn main() {
    let mut wb = WorldBuilder::new();
    wb.register::<u64>(42);
    wb.register::<u32>(7);
    let mut world = wb.build();
    let r = world.registry_mut();

    // --- Bare 3-stage pipeline (no Option, no World access) ---

    let mut bare = PipelineStart::<u64>::new()
        .stage(|x: u64| x.wrapping_mul(3), r)
        .stage(|x: u64| x.wrapping_add(7), r)
        .stage(|x: u64| x >> 1, r);

    // --- Option 3-stage pipeline ---

    let mut option = PipelineStart::<u64>::new()
        .stage(
            |x: u64| -> Option<u64> { if x > 0 { Some(x) } else { None } },
            r,
        )
        .map(|x: u64| x.wrapping_mul(3), r)
        .filter(|_w, x| *x < 1_000_000);

    // --- World-accessing pipeline (pre-resolved via Res<T>) ---

    let mut world_resolved = PipelineStart::<u64>::new()
        .stage(add_resource, r)
        .stage(mul_resource, r);

    // --- World-accessing 3-stage pipeline ---

    let mut stage_3 = PipelineStart::<u64>::new()
        .stage(add_resource, r)
        .stage(mul_resource, r)
        .stage(sub_resource, r);

    // --- Built (boxed) pipeline ---

    let mut boxed = PipelineStart::<u64>::new()
        .stage(|x: u64| x.wrapping_mul(3), r)
        .stage(|x: u64| x.wrapping_add(7), r)
        .stage(|_x: u64| {}, r)
        .build();

    // --- Batch pipelines (same chains as their linear counterparts) ---

    fn sink(mut acc: ResMut<u64>, x: u64) {
        *acc = acc.wrapping_add(x);
    }

    // Bare: 3 compute stages + sink (same chain for both batch and linear)
    let mut batch_bare = PipelineStart::<u64>::new()
        .stage(|x: u64| x.wrapping_mul(3), r)
        .stage(|x: u64| x.wrapping_add(7), r)
        .stage(sink, r)
        .build_batch(1024);

    let mut linear_bare = PipelineStart::<u64>::new()
        .stage(|x: u64| x.wrapping_mul(3), r)
        .stage(|x: u64| x.wrapping_add(7), r)
        .stage(sink, r);

    // Res<T>: 3 world-access stages + sink (same chain for both)
    let mut batch_res = PipelineStart::<u64>::new()
        .stage(add_resource, r)
        .stage(mul_resource, r)
        .stage(sub_resource, r)
        .stage(sink, r)
        .build_batch(1024);

    let mut linear_res = PipelineStart::<u64>::new()
        .stage(add_resource, r)
        .stage(mul_resource, r)
        .stage(sub_resource, r)
        .stage(sink, r);

    // --- Result→catch→map→unwrap_or ---

    let mut catch_pipeline = PipelineStart::<u64>::new()
        .stage(
            |x: u64| -> Result<u64, &'static str> { if x > 0 { Ok(x) } else { Err("zero") } },
            r,
        )
        .catch(|_err: &'static str| {}, r)
        .map(|x: u64| x.wrapping_mul(2), r)
        .unwrap_or(0);

    // --- Handler dispatch setup ---

    let mut sys_res = handler_res_read.into_handler(world.registry_mut());
    let mut sys_res_mut = handler_res_mut_write.into_handler(world.registry_mut());
    let mut sys_two = handler_two_res.into_handler(world.registry_mut());
    let mut sys_dyn: Box<dyn Handler<u64>> =
        Box::new(handler_res_read.into_handler(world.registry_mut()));

    // --- Pipeline benchmarks ---

    print_header("Pipeline Dispatch Latency (cycles)");

    let mut input = 1u64;

    bench_batched("baseline (hand-written fn)", || {
        input = input.wrapping_add(1);
        baseline_handwritten(&mut world, black_box(input))
    });

    bench_batched("bare 3-stage pipe", || {
        input = input.wrapping_add(1);
        bare_3stage_run(&mut bare, &mut world, black_box(input))
    });

    bench_batched("option 3-stage (Some path)", || {
        input = input.wrapping_add(1);
        option_3stage_run(&mut option, &mut world, black_box(input + 1)).unwrap_or(0)
    });

    bench_batched("option 3-stage (None path)", || {
        option_3stage_run(&mut option, &mut world, black_box(0)).unwrap_or(0)
    });

    bench_batched("world-access 2-stage (Res<T>)", || {
        input = input.wrapping_add(1);
        world_access_run(&mut world_resolved, &mut world, black_box(input))
    });

    bench_batched("boxed Pipeline (dyn dispatch)", || {
        input = input.wrapping_add(1);
        boxed_pipeline_run(&mut boxed, &mut world, black_box(input));
        0
    });

    bench_batched("result→catch→map→unwrap_or", || {
        input = input.wrapping_add(1);
        catch_pipeline.run(&mut world, black_box(input))
    });

    // --- Handler dispatch benchmarks ---

    println!();
    print_header("Handler Dispatch Latency (cycles)");

    bench_batched("Handler + Res<u64> (read)", || {
        input = input.wrapping_add(1);
        probe_handler_res_read(&mut sys_res, &mut world, black_box(input));
        0
    });

    bench_batched("Handler + ResMut<u64> (write+stamp)", || {
        input = input.wrapping_add(1);
        probe_handler_res_mut(&mut sys_res_mut, &mut world, black_box(input));
        0
    });

    bench_batched("Handler + 2x Res (tuple fetch)", || {
        input = input.wrapping_add(1);
        probe_handler_two_res(&mut sys_two, &mut world, black_box(input));
        0
    });

    bench_batched("Box<dyn Handler> + Res<u64>", || {
        input = input.wrapping_add(1);
        probe_dyn_handler(&mut *sys_dyn, &mut world, black_box(input));
        0
    });

    // --- Stage pipeline with Res<T> (3-stage) ---

    println!();
    print_header("Stage Pipeline with Res<T> (cycles)");

    bench_batched("3-stage pipeline (Res<T>)", || {
        input = input.wrapping_add(1);
        stage_3.run(&mut world, black_box(input))
    });

    // --- Batch vs Linear throughput (total cycles for 100 items) ---

    println!();
    print_header("Batch vs Linear Throughput (total cycles, 100 items)");

    let items_100: Vec<u64> = (0..100).collect();

    // Batch bare: fill + run
    {
        for _ in 0..WARMUP {
            batch_bare.input_mut().extend_from_slice(&items_100);
            batch_bare.run(&mut world);
        }
        let mut samples = Vec::with_capacity(ITERATIONS);
        for _ in 0..ITERATIONS {
            batch_bare.input_mut().extend_from_slice(&items_100);
            let start = rdtsc_start();
            batch_bare.run(&mut world);
            let end = rdtsc_end();
            samples.push(end.wrapping_sub(start));
        }
        samples.sort_unstable();
        println!(
            "{:<44} {:>8} {:>8} {:>8}",
            "batch bare (100 items)",
            percentile(&samples, 50.0),
            percentile(&samples, 99.0),
            percentile(&samples, 99.9),
        );
    }

    // Linear bare: 100 individual calls (same chain)
    {
        for _ in 0..WARMUP {
            for i in 0..100u64 {
                linear_bare.run(&mut world, black_box(i));
            }
        }
        let mut samples = Vec::with_capacity(ITERATIONS);
        for _ in 0..ITERATIONS {
            let start = rdtsc_start();
            for i in 0..100u64 {
                linear_bare.run(&mut world, black_box(i));
            }
            let end = rdtsc_end();
            samples.push(end.wrapping_sub(start));
        }
        samples.sort_unstable();
        println!(
            "{:<44} {:>8} {:>8} {:>8}",
            "linear bare (100 calls)",
            percentile(&samples, 50.0),
            percentile(&samples, 99.0),
            percentile(&samples, 99.9),
        );
    }

    // Batch Res<T>: fill + run
    {
        for _ in 0..WARMUP {
            batch_res.input_mut().extend_from_slice(&items_100);
            batch_res.run(&mut world);
        }
        let mut samples = Vec::with_capacity(ITERATIONS);
        for _ in 0..ITERATIONS {
            batch_res.input_mut().extend_from_slice(&items_100);
            let start = rdtsc_start();
            batch_res.run(&mut world);
            let end = rdtsc_end();
            samples.push(end.wrapping_sub(start));
        }
        samples.sort_unstable();
        println!(
            "{:<44} {:>8} {:>8} {:>8}",
            "batch Res<T> (100 items)",
            percentile(&samples, 50.0),
            percentile(&samples, 99.0),
            percentile(&samples, 99.9),
        );
    }

    // Linear Res<T>: 100 individual calls (same chain)
    {
        for _ in 0..WARMUP {
            for i in 0..100u64 {
                linear_res.run(&mut world, black_box(i));
            }
        }
        let mut samples = Vec::with_capacity(ITERATIONS);
        for _ in 0..ITERATIONS {
            let start = rdtsc_start();
            for i in 0..100u64 {
                linear_res.run(&mut world, black_box(i));
            }
            let end = rdtsc_end();
            samples.push(end.wrapping_sub(start));
        }
        samples.sort_unstable();
        println!(
            "{:<44} {:>8} {:>8} {:>8}",
            "linear Res<T> (100 calls)",
            percentile(&samples, 50.0),
            percentile(&samples, 99.0),
            percentile(&samples, 99.9),
        );
    }

    // --- inputs_changed cost ---

    println!();
    print_header("inputs_changed Latency (cycles)");

    // Build a world with enough resources for 8-param handlers.
    let mut ic_wb = WorldBuilder::new();
    ic_wb.register::<u64>(0);
    ic_wb.register::<u32>(0);
    ic_wb.register::<bool>(false);
    ic_wb.register::<f64>(0.0);
    ic_wb.register::<i64>(0);
    ic_wb.register::<i32>(0);
    ic_wb.register::<u8>(0);
    ic_wb.register::<u16>(0);
    let mut ic_world = ic_wb.build();
    let ic_r = ic_world.registry_mut();

    let ic1 = ic_1p.into_handler(ic_r);
    let ic2 = ic_2p.into_handler(ic_r);
    let ic4 = ic_4p.into_handler(ic_r);
    let ic8 = ic_8p.into_handler(ic_r);

    // Tick 0: all changed (changed_at == current_sequence).
    bench_batched("inputs_changed 1-param (changed)", || {
        if ic1.inputs_changed(&ic_world) { 1 } else { 0 }
    });

    bench_batched("inputs_changed 2-param (changed)", || {
        if ic2.inputs_changed(&ic_world) { 1 } else { 0 }
    });

    bench_batched("inputs_changed 4-param (changed)", || {
        if ic4.inputs_changed(&ic_world) { 1 } else { 0 }
    });

    bench_batched("inputs_changed 8-param (changed)", || {
        if ic8.inputs_changed(&ic_world) { 1 } else { 0 }
    });

    // Advance tick so inputs are stale.
    ic_world.next_sequence();

    bench_batched("inputs_changed 1-param (stale)", || {
        if ic1.inputs_changed(&ic_world) { 1 } else { 0 }
    });

    bench_batched("inputs_changed 2-param (stale)", || {
        if ic2.inputs_changed(&ic_world) { 1 } else { 0 }
    });

    bench_batched("inputs_changed 4-param (stale)", || {
        if ic4.inputs_changed(&ic_world) { 1 } else { 0 }
    });

    bench_batched("inputs_changed 8-param (stale)", || {
        if ic8.inputs_changed(&ic_world) { 1 } else { 0 }
    });

    println!();
}

pub fn id<T: 'static>(&self) -> ResourceId

Resolve the ResourceId for a type. Cold path — uses HashMap lookup.

Panics

Panics if the resource type was not registered.

pub fn try_id<T: 'static>(&self) -> Option<ResourceId>

Try to resolve the ResourceId for a type. Returns None if the type was not registered.

pub fn len(&self) -> usize

Returns the number of registered resources.

pub fn is_empty(&self) -> bool

Returns true if no resources are stored.

pub fn contains<T: 'static>(&self) -> bool

Returns true if a resource of type T is stored.

pub fn resource<T: 'static>(&self) -> &T

Safe shared access to a resource. Cold path — resolves via HashMap.

Takes &self — multiple shared references can coexist. The borrow checker prevents mixing with resource_mut (which takes &mut self).

Panics

Panics if the resource type was not registered.

Examples found in repository

examples/optional_resources.rs (line 93)

fn main() {
    println!("=== Scenario 1: All optional resources present ===\n");
    {
        let mut builder = WorldBuilder::new();
        builder
            .register(Config { threshold: 5.0 })
            .register(DebugLog {
                entries: Vec::new(),
            })
            .register(Metrics {
                events_processed: 0,
            });
        let mut world = builder.build();

        let mut process = process_event.into_handler(world.registry_mut());
        let mut track = track_metrics.into_handler(world.registry_mut());

        for value in [3.0, 7.5, 1.2] {
            process.run(&mut world, value);
            track.run(&mut world, value);
            println!();
        }

        let log = world.resource::<DebugLog>();
        println!("Debug log entries: {:?}", log.entries);

        let metrics = world.resource::<Metrics>();
        println!("Events processed: {}", metrics.events_processed);
    }

    println!("\n=== Scenario 2: No optional resources ===\n");
    {
        let mut builder = WorldBuilder::new();
        builder.register(Config { threshold: 5.0 });
        // DebugLog and Metrics intentionally not registered.
        let mut world = builder.build();

        let mut process = process_event.into_handler(world.registry_mut());
        let mut track = track_metrics.into_handler(world.registry_mut());

        for value in [3.0, 7.5] {
            process.run(&mut world, value);
            track.run(&mut world, value);
            println!();
        }

        println!("Handlers ran cleanly without optional resources.");
    }

    println!("\nDone.");
}

examples/local_state.rs (line 82)

fn main() {
    println!("=== Example 1: Simple counter ===\n");
    {
        let mut world = WorldBuilder::new().build();
        let mut sys = counting_handler.into_handler(world.registry_mut());

        sys.run(&mut world, "alpha");
        sys.run(&mut world, "beta");
        sys.run(&mut world, "gamma");
    }

    println!("\n=== Example 2: Independent instances ===\n");
    {
        let mut builder = WorldBuilder::new();
        builder.register::<i64>(0);
        let mut world = builder.build();

        // Two handlers from the same function — each has its own Local<i64>.
        let mut sys_a = accumulator.into_handler(world.registry_mut());
        let mut sys_b = accumulator.into_handler(world.registry_mut());

        println!("sys_a gets 10:");
        sys_a.run(&mut world, 10i64);

        println!("sys_b gets 20:");
        sys_b.run(&mut world, 20i64);

        println!("sys_a gets 5:");
        sys_a.run(&mut world, 5i64);

        // sys_a local: 15, sys_b local: 20, world total: 35
        println!("\nWorld total: {}", world.resource::<i64>());
        assert_eq!(*world.resource::<i64>(), 35);
    }

    println!("\n=== Example 3: Batch buffer ===\n");
    {
        let mut builder = WorldBuilder::new();
        builder.register::<Vec<u32>>(Vec::new());
        let mut world = builder.build();

        let mut sys = batch_writer.into_handler(world.registry_mut());

        // First two events accumulate locally.
        sys.run(&mut world, 1u32);
        println!("  output len: {}", world.resource::<Vec<u32>>().len());

        sys.run(&mut world, 2u32);
        println!("  output len: {}", world.resource::<Vec<u32>>().len());

        // Third event triggers flush.
        sys.run(&mut world, 3u32);
        println!("  output len: {}", world.resource::<Vec<u32>>().len());

        // Fourth event starts a new batch.
        sys.run(&mut world, 4u32);
        println!("  output len: {}", world.resource::<Vec<u32>>().len());

        let output = world.resource::<Vec<u32>>();
        println!("\nFinal output: {:?}", &*output);
        assert_eq!(&*output, &[1, 2, 3]);
    }

    println!("\nDone.");
}

examples/pipeline.rs (line 140)

fn main() {
    // --- Bare value pipeline: arity-0 closure stages ---

    println!("=== Bare Value Pipeline ===\n");

    let mut world = WorldBuilder::new().build();
    let r = world.registry_mut();

    let mut bare_pipeline = PipelineStart::<u32>::new()
        .stage(|x: u32| x * 2, r)
        .stage(|x: u32| x + 1, r);

    println!("  5 → {}", bare_pipeline.run(&mut world, 5));
    println!("  10 → {}", bare_pipeline.run(&mut world, 10));

    // --- Option pipeline: filter + inspect (cold path), map (hot path) ---

    println!("\n=== Option Pipeline ===\n");

    let mut wb = WorldBuilder::new();
    wb.register(PriceCache::new());
    let mut world = wb.build();
    let r = world.registry_mut();

    let mut option_pipeline = PipelineStart::<MarketTick>::new()
        .stage(
            |tick: MarketTick| -> Option<MarketTick> {
                if tick.price > 0.0 { Some(tick) } else { None }
            },
            r,
        )
        .filter(|_w, tick| tick.symbol == "BTC")
        .inspect(|_w, tick| {
            println!("  [inspect] {} @ {:.2}", tick.symbol, tick.price);
        })
        .map(store_price, r);

    let ticks = [
        MarketTick {
            symbol: "BTC",
            price: 50_000.0,
        },
        MarketTick {
            symbol: "ETH",
            price: 3_000.0,
        }, // filtered: not BTC
        MarketTick {
            symbol: "BTC",
            price: -1.0,
        }, // filtered: negative
        MarketTick {
            symbol: "BTC",
            price: 51_000.0,
        },
    ];

    for tick in ticks {
        option_pipeline.run(&mut world, tick);
    }

    let cache = world.resource::<PriceCache>();
    println!(
        "\n  PriceCache: latest={:.2}, updates={}",
        cache.latest, cache.updates
    );
    assert_eq!(cache.updates, 2);
    assert_eq!(cache.latest, 51_000.0);

    // --- Result pipeline: validate → check → catch → store ---

    println!("\n=== Result Pipeline with catch ===\n");

    let mut wb = WorldBuilder::new();
    wb.register(PriceCache::new());
    wb.register::<u64>(0); // error counter
    let mut world = wb.build();
    let r = world.registry_mut();

    let mut result_pipeline = PipelineStart::<MarketTick>::new()
        .stage(validate, r)
        .and_then(check_known, r)
        .catch(count_error, r)
        .map(store_price, r);

    let ticks = [
        MarketTick {
            symbol: "BTC",
            price: 52_000.0,
        },
        MarketTick {
            symbol: "XYZ",
            price: 100.0,
        }, // unknown symbol → catch
        MarketTick {
            symbol: "ETH",
            price: -5.0,
        }, // invalid price → catch
        MarketTick {
            symbol: "ETH",
            price: 3_500.0,
        },
    ];

    for tick in ticks {
        result_pipeline.run(&mut world, tick);
    }

    let errors = *world.resource::<u64>();
    println!("\n  Errors: {errors}");
    assert_eq!(errors, 2);

    // --- Build into Handler ---

    println!("\n=== Pipeline as Handler ===\n");

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

    let mut pipeline = PipelineStart::<u32>::new().stage(accumulate, r).build();

    pipeline.run(&mut world, 10);
    pipeline.run(&mut world, 20);
    pipeline.run(&mut world, 30);

    let total = *world.resource::<u64>();
    println!("  Total: {total}");
    assert_eq!(total, 60);

    println!("\nDone.");
}

examples/mock_runtime.rs (line 240)

fn main() {
    // -- Build ----------------------------------------------------------------

    let mut wb = WorldBuilder::new();
    wb.install_plugin(TradingPlugin {
        initial_prices: vec![("BTC", 50_000.0), ("ETH", 3_000.0)],
        risk_cap: 100,
    });
    let mut md = wb.install_driver(MarketDataInstaller);
    let mut world = wb.build();

    // Standalone handler — demonstrates change detection.
    fn on_signal(signals: Res<SignalBuffer>, _event: ()) {
        black_box(signals.signals.len());
    }
    let mut signal_handler = on_signal.into_handler(world.registry_mut());

    // -- Correctness check ----------------------------------------------------

    let ticks = [
        MarketTick {
            symbol: "BTC",
            price: 50_100.0,
        }, // delta=100 > 50 → signal
        MarketTick {
            symbol: "ETH",
            price: 3_010.0,
        }, // delta=10 < 50 → no signal
        MarketTick {
            symbol: "BTC",
            price: 49_900.0,
        }, // delta=200 > 50 → signal
    ];

    md.poll(&mut world, &ticks);

    // 2 signals accepted, risk cap=100 so both go through.
    assert_eq!(world.resource::<OrderCount>().0, 2);

    // Change detection: SignalBuffer was modified → handler should run.
    assert!(signal_handler.inputs_changed(&world));
    signal_handler.run(&mut world, ());

    // Advance sequence, no new writes → handler should skip.
    world.next_sequence();
    assert!(!signal_handler.inputs_changed(&world));

    println!("Correctness checks passed.\n");

    // -- Latency measurement --------------------------------------------------

    const WARMUP: usize = 1_000;
    const ITERATIONS: usize = 1_000;

    // Ticks that exercise the full pipeline path (signal detection + cache write).
    let bench_ticks = [
        MarketTick {
            symbol: "BTC",
            price: 50_100.0,
        },
        MarketTick {
            symbol: "ETH",
            price: 3_100.0,
        },
        MarketTick {
            symbol: "BTC",
            price: 50_200.0,
        },
        MarketTick {
            symbol: "ETH",
            price: 3_200.0,
        },
    ];

    println!(
        "=== nexus-rt Dispatch Latency (cycles, {} iterations) ===\n",
        ITERATIONS
    );
    println!(
        "{:<44} {:>8} {:>8} {:>8}",
        "Operation", "p50", "p99", "p999"
    );
    println!("{}", "-".repeat(72));

    // Single tick through dyn pipeline
    {
        let tick = bench_ticks[0];
        for _ in 0..WARMUP {
            world.next_sequence();
            md.pipeline.run(&mut world, black_box(tick));
        }
        let mut samples = Vec::with_capacity(ITERATIONS);
        for _ in 0..ITERATIONS {
            world.next_sequence();
            let start = rdtsc_start();
            md.pipeline.run(&mut world, black_box(tick));
            let end = rdtsc_end();
            samples.push(end.wrapping_sub(start));
        }
        report("single tick (dyn pipeline, 3 stages)", &mut samples);
    }

    // Standalone handler (1 param, Res<T>)
    {
        for _ in 0..WARMUP {
            black_box(());
            signal_handler.run(&mut world, ());
        }
        let mut samples = Vec::with_capacity(ITERATIONS);
        for _ in 0..ITERATIONS {
            let start = rdtsc_start();
            black_box(());
            signal_handler.run(&mut world, ());
            let end = rdtsc_end();
            samples.push(end.wrapping_sub(start));
        }
        report("handler dispatch (1 param, Res<T>)", &mut samples);
    }

    // 4-tick batch through driver poll
    {
        for _ in 0..WARMUP {
            md.poll(&mut world, &bench_ticks);
        }
        let mut samples = Vec::with_capacity(ITERATIONS);
        for _ in 0..ITERATIONS {
            let start = rdtsc_start();
            md.poll(&mut world, black_box(&bench_ticks));
            let end = rdtsc_end();
            samples.push(end.wrapping_sub(start));
        }
        let mut per_tick: Vec<u64> = samples
            .iter()
            .map(|&s| s / bench_ticks.len() as u64)
            .collect();
        report("4-tick poll (total)", &mut samples);
        report("4-tick poll (per tick)", &mut per_tick);
    }

    // Change detection
    {
        world.next_sequence(); // ensure stale
        for _ in 0..WARMUP {
            black_box(signal_handler.inputs_changed(&world));
        }
        let mut samples = Vec::with_capacity(ITERATIONS);
        for _ in 0..ITERATIONS {
            let start = rdtsc_start();
            black_box(signal_handler.inputs_changed(&world));
            let end = rdtsc_end();
            samples.push(end.wrapping_sub(start));
        }
        report("inputs_changed (1 param, stale)", &mut samples);
    }

    println!();
}

pub fn resource_mut<T: 'static>(&mut self) -> &mut T

Safe exclusive access to a resource. Cold path — resolves via HashMap.

Panics

Panics if the resource type was not registered.

pub fn current_sequence(&self) -> Sequence

Returns the current event sequence number.

pub fn next_sequence(&mut self) -> Sequence

Advance to the next event sequence number and return it.

Drivers call this before dispatching each event. The returned sequence number identifies the event being processed. Resources mutated during dispatch will record this sequence in changed_at.

Examples found in repository

examples/mock_runtime.rs (line 194)

    fn poll(&mut self, world: &mut World, ticks: &[MarketTick]) {
        if ticks.is_empty() {
            return;
        }
        world.next_sequence();
        for tick in ticks {
            self.pipeline.run(world, *tick);
        }
    }
}

// ── main ────────────────────────────────────────────────────────────────

fn main() {
    // -- Build ----------------------------------------------------------------

    let mut wb = WorldBuilder::new();
    wb.install_plugin(TradingPlugin {
        initial_prices: vec![("BTC", 50_000.0), ("ETH", 3_000.0)],
        risk_cap: 100,
    });
    let mut md = wb.install_driver(MarketDataInstaller);
    let mut world = wb.build();

    // Standalone handler — demonstrates change detection.
    fn on_signal(signals: Res<SignalBuffer>, _event: ()) {
        black_box(signals.signals.len());
    }
    let mut signal_handler = on_signal.into_handler(world.registry_mut());

    // -- Correctness check ----------------------------------------------------

    let ticks = [
        MarketTick {
            symbol: "BTC",
            price: 50_100.0,
        }, // delta=100 > 50 → signal
        MarketTick {
            symbol: "ETH",
            price: 3_010.0,
        }, // delta=10 < 50 → no signal
        MarketTick {
            symbol: "BTC",
            price: 49_900.0,
        }, // delta=200 > 50 → signal
    ];

    md.poll(&mut world, &ticks);

    // 2 signals accepted, risk cap=100 so both go through.
    assert_eq!(world.resource::<OrderCount>().0, 2);

    // Change detection: SignalBuffer was modified → handler should run.
    assert!(signal_handler.inputs_changed(&world));
    signal_handler.run(&mut world, ());

    // Advance sequence, no new writes → handler should skip.
    world.next_sequence();
    assert!(!signal_handler.inputs_changed(&world));

    println!("Correctness checks passed.\n");

    // -- Latency measurement --------------------------------------------------

    const WARMUP: usize = 1_000;
    const ITERATIONS: usize = 1_000;

    // Ticks that exercise the full pipeline path (signal detection + cache write).
    let bench_ticks = [
        MarketTick {
            symbol: "BTC",
            price: 50_100.0,
        },
        MarketTick {
            symbol: "ETH",
            price: 3_100.0,
        },
        MarketTick {
            symbol: "BTC",
            price: 50_200.0,
        },
        MarketTick {
            symbol: "ETH",
            price: 3_200.0,
        },
    ];

    println!(
        "=== nexus-rt Dispatch Latency (cycles, {} iterations) ===\n",
        ITERATIONS
    );
    println!(
        "{:<44} {:>8} {:>8} {:>8}",
        "Operation", "p50", "p99", "p999"
    );
    println!("{}", "-".repeat(72));

    // Single tick through dyn pipeline
    {
        let tick = bench_ticks[0];
        for _ in 0..WARMUP {
            world.next_sequence();
            md.pipeline.run(&mut world, black_box(tick));
        }
        let mut samples = Vec::with_capacity(ITERATIONS);
        for _ in 0..ITERATIONS {
            world.next_sequence();
            let start = rdtsc_start();
            md.pipeline.run(&mut world, black_box(tick));
            let end = rdtsc_end();
            samples.push(end.wrapping_sub(start));
        }
        report("single tick (dyn pipeline, 3 stages)", &mut samples);
    }

    // Standalone handler (1 param, Res<T>)
    {
        for _ in 0..WARMUP {
            black_box(());
            signal_handler.run(&mut world, ());
        }
        let mut samples = Vec::with_capacity(ITERATIONS);
        for _ in 0..ITERATIONS {
            let start = rdtsc_start();
            black_box(());
            signal_handler.run(&mut world, ());
            let end = rdtsc_end();
            samples.push(end.wrapping_sub(start));
        }
        report("handler dispatch (1 param, Res<T>)", &mut samples);
    }

    // 4-tick batch through driver poll
    {
        for _ in 0..WARMUP {
            md.poll(&mut world, &bench_ticks);
        }
        let mut samples = Vec::with_capacity(ITERATIONS);
        for _ in 0..ITERATIONS {
            let start = rdtsc_start();
            md.poll(&mut world, black_box(&bench_ticks));
            let end = rdtsc_end();
            samples.push(end.wrapping_sub(start));
        }
        let mut per_tick: Vec<u64> = samples
            .iter()
            .map(|&s| s / bench_ticks.len() as u64)
            .collect();
        report("4-tick poll (total)", &mut samples);
        report("4-tick poll (per tick)", &mut per_tick);
    }

    // Change detection
    {
        world.next_sequence(); // ensure stale
        for _ in 0..WARMUP {
            black_box(signal_handler.inputs_changed(&world));
        }
        let mut samples = Vec::with_capacity(ITERATIONS);
        for _ in 0..ITERATIONS {
            let start = rdtsc_start();
            black_box(signal_handler.inputs_changed(&world));
            let end = rdtsc_end();
            samples.push(end.wrapping_sub(start));
        }
        report("inputs_changed (1 param, stale)", &mut samples);
    }

    println!();
}

examples/perf_pipeline.rs (line 560)

fn main() {
    let mut wb = WorldBuilder::new();
    wb.register::<u64>(42);
    wb.register::<u32>(7);
    let mut world = wb.build();
    let r = world.registry_mut();

    // --- Bare 3-stage pipeline (no Option, no World access) ---

    let mut bare = PipelineStart::<u64>::new()
        .stage(|x: u64| x.wrapping_mul(3), r)
        .stage(|x: u64| x.wrapping_add(7), r)
        .stage(|x: u64| x >> 1, r);

    // --- Option 3-stage pipeline ---

    let mut option = PipelineStart::<u64>::new()
        .stage(
            |x: u64| -> Option<u64> { if x > 0 { Some(x) } else { None } },
            r,
        )
        .map(|x: u64| x.wrapping_mul(3), r)
        .filter(|_w, x| *x < 1_000_000);

    // --- World-accessing pipeline (pre-resolved via Res<T>) ---

    let mut world_resolved = PipelineStart::<u64>::new()
        .stage(add_resource, r)
        .stage(mul_resource, r);

    // --- World-accessing 3-stage pipeline ---

    let mut stage_3 = PipelineStart::<u64>::new()
        .stage(add_resource, r)
        .stage(mul_resource, r)
        .stage(sub_resource, r);

    // --- Built (boxed) pipeline ---

    let mut boxed = PipelineStart::<u64>::new()
        .stage(|x: u64| x.wrapping_mul(3), r)
        .stage(|x: u64| x.wrapping_add(7), r)
        .stage(|_x: u64| {}, r)
        .build();

    // --- Batch pipelines (same chains as their linear counterparts) ---

    fn sink(mut acc: ResMut<u64>, x: u64) {
        *acc = acc.wrapping_add(x);
    }

    // Bare: 3 compute stages + sink (same chain for both batch and linear)
    let mut batch_bare = PipelineStart::<u64>::new()
        .stage(|x: u64| x.wrapping_mul(3), r)
        .stage(|x: u64| x.wrapping_add(7), r)
        .stage(sink, r)
        .build_batch(1024);

    let mut linear_bare = PipelineStart::<u64>::new()
        .stage(|x: u64| x.wrapping_mul(3), r)
        .stage(|x: u64| x.wrapping_add(7), r)
        .stage(sink, r);

    // Res<T>: 3 world-access stages + sink (same chain for both)
    let mut batch_res = PipelineStart::<u64>::new()
        .stage(add_resource, r)
        .stage(mul_resource, r)
        .stage(sub_resource, r)
        .stage(sink, r)
        .build_batch(1024);

    let mut linear_res = PipelineStart::<u64>::new()
        .stage(add_resource, r)
        .stage(mul_resource, r)
        .stage(sub_resource, r)
        .stage(sink, r);

    // --- Result→catch→map→unwrap_or ---

    let mut catch_pipeline = PipelineStart::<u64>::new()
        .stage(
            |x: u64| -> Result<u64, &'static str> { if x > 0 { Ok(x) } else { Err("zero") } },
            r,
        )
        .catch(|_err: &'static str| {}, r)
        .map(|x: u64| x.wrapping_mul(2), r)
        .unwrap_or(0);

    // --- Handler dispatch setup ---

    let mut sys_res = handler_res_read.into_handler(world.registry_mut());
    let mut sys_res_mut = handler_res_mut_write.into_handler(world.registry_mut());
    let mut sys_two = handler_two_res.into_handler(world.registry_mut());
    let mut sys_dyn: Box<dyn Handler<u64>> =
        Box::new(handler_res_read.into_handler(world.registry_mut()));

    // --- Pipeline benchmarks ---

    print_header("Pipeline Dispatch Latency (cycles)");

    let mut input = 1u64;

    bench_batched("baseline (hand-written fn)", || {
        input = input.wrapping_add(1);
        baseline_handwritten(&mut world, black_box(input))
    });

    bench_batched("bare 3-stage pipe", || {
        input = input.wrapping_add(1);
        bare_3stage_run(&mut bare, &mut world, black_box(input))
    });

    bench_batched("option 3-stage (Some path)", || {
        input = input.wrapping_add(1);
        option_3stage_run(&mut option, &mut world, black_box(input + 1)).unwrap_or(0)
    });

    bench_batched("option 3-stage (None path)", || {
        option_3stage_run(&mut option, &mut world, black_box(0)).unwrap_or(0)
    });

    bench_batched("world-access 2-stage (Res<T>)", || {
        input = input.wrapping_add(1);
        world_access_run(&mut world_resolved, &mut world, black_box(input))
    });

    bench_batched("boxed Pipeline (dyn dispatch)", || {
        input = input.wrapping_add(1);
        boxed_pipeline_run(&mut boxed, &mut world, black_box(input));
        0
    });

    bench_batched("result→catch→map→unwrap_or", || {
        input = input.wrapping_add(1);
        catch_pipeline.run(&mut world, black_box(input))
    });

    // --- Handler dispatch benchmarks ---

    println!();
    print_header("Handler Dispatch Latency (cycles)");

    bench_batched("Handler + Res<u64> (read)", || {
        input = input.wrapping_add(1);
        probe_handler_res_read(&mut sys_res, &mut world, black_box(input));
        0
    });

    bench_batched("Handler + ResMut<u64> (write+stamp)", || {
        input = input.wrapping_add(1);
        probe_handler_res_mut(&mut sys_res_mut, &mut world, black_box(input));
        0
    });

    bench_batched("Handler + 2x Res (tuple fetch)", || {
        input = input.wrapping_add(1);
        probe_handler_two_res(&mut sys_two, &mut world, black_box(input));
        0
    });

    bench_batched("Box<dyn Handler> + Res<u64>", || {
        input = input.wrapping_add(1);
        probe_dyn_handler(&mut *sys_dyn, &mut world, black_box(input));
        0
    });

    // --- Stage pipeline with Res<T> (3-stage) ---

    println!();
    print_header("Stage Pipeline with Res<T> (cycles)");

    bench_batched("3-stage pipeline (Res<T>)", || {
        input = input.wrapping_add(1);
        stage_3.run(&mut world, black_box(input))
    });

    // --- Batch vs Linear throughput (total cycles for 100 items) ---

    println!();
    print_header("Batch vs Linear Throughput (total cycles, 100 items)");

    let items_100: Vec<u64> = (0..100).collect();

    // Batch bare: fill + run
    {
        for _ in 0..WARMUP {
            batch_bare.input_mut().extend_from_slice(&items_100);
            batch_bare.run(&mut world);
        }
        let mut samples = Vec::with_capacity(ITERATIONS);
        for _ in 0..ITERATIONS {
            batch_bare.input_mut().extend_from_slice(&items_100);
            let start = rdtsc_start();
            batch_bare.run(&mut world);
            let end = rdtsc_end();
            samples.push(end.wrapping_sub(start));
        }
        samples.sort_unstable();
        println!(
            "{:<44} {:>8} {:>8} {:>8}",
            "batch bare (100 items)",
            percentile(&samples, 50.0),
            percentile(&samples, 99.0),
            percentile(&samples, 99.9),
        );
    }

    // Linear bare: 100 individual calls (same chain)
    {
        for _ in 0..WARMUP {
            for i in 0..100u64 {
                linear_bare.run(&mut world, black_box(i));
            }
        }
        let mut samples = Vec::with_capacity(ITERATIONS);
        for _ in 0..ITERATIONS {
            let start = rdtsc_start();
            for i in 0..100u64 {
                linear_bare.run(&mut world, black_box(i));
            }
            let end = rdtsc_end();
            samples.push(end.wrapping_sub(start));
        }
        samples.sort_unstable();
        println!(
            "{:<44} {:>8} {:>8} {:>8}",
            "linear bare (100 calls)",
            percentile(&samples, 50.0),
            percentile(&samples, 99.0),
            percentile(&samples, 99.9),
        );
    }

    // Batch Res<T>: fill + run
    {
        for _ in 0..WARMUP {
            batch_res.input_mut().extend_from_slice(&items_100);
            batch_res.run(&mut world);
        }
        let mut samples = Vec::with_capacity(ITERATIONS);
        for _ in 0..ITERATIONS {
            batch_res.input_mut().extend_from_slice(&items_100);
            let start = rdtsc_start();
            batch_res.run(&mut world);
            let end = rdtsc_end();
            samples.push(end.wrapping_sub(start));
        }
        samples.sort_unstable();
        println!(
            "{:<44} {:>8} {:>8} {:>8}",
            "batch Res<T> (100 items)",
            percentile(&samples, 50.0),
            percentile(&samples, 99.0),
            percentile(&samples, 99.9),
        );
    }

    // Linear Res<T>: 100 individual calls (same chain)
    {
        for _ in 0..WARMUP {
            for i in 0..100u64 {
                linear_res.run(&mut world, black_box(i));
            }
        }
        let mut samples = Vec::with_capacity(ITERATIONS);
        for _ in 0..ITERATIONS {
            let start = rdtsc_start();
            for i in 0..100u64 {
                linear_res.run(&mut world, black_box(i));
            }
            let end = rdtsc_end();
            samples.push(end.wrapping_sub(start));
        }
        samples.sort_unstable();
        println!(
            "{:<44} {:>8} {:>8} {:>8}",
            "linear Res<T> (100 calls)",
            percentile(&samples, 50.0),
            percentile(&samples, 99.0),
            percentile(&samples, 99.9),
        );
    }

    // --- inputs_changed cost ---

    println!();
    print_header("inputs_changed Latency (cycles)");

    // Build a world with enough resources for 8-param handlers.
    let mut ic_wb = WorldBuilder::new();
    ic_wb.register::<u64>(0);
    ic_wb.register::<u32>(0);
    ic_wb.register::<bool>(false);
    ic_wb.register::<f64>(0.0);
    ic_wb.register::<i64>(0);
    ic_wb.register::<i32>(0);
    ic_wb.register::<u8>(0);
    ic_wb.register::<u16>(0);
    let mut ic_world = ic_wb.build();
    let ic_r = ic_world.registry_mut();

    let ic1 = ic_1p.into_handler(ic_r);
    let ic2 = ic_2p.into_handler(ic_r);
    let ic4 = ic_4p.into_handler(ic_r);
    let ic8 = ic_8p.into_handler(ic_r);

    // Tick 0: all changed (changed_at == current_sequence).
    bench_batched("inputs_changed 1-param (changed)", || {
        if ic1.inputs_changed(&ic_world) { 1 } else { 0 }
    });

    bench_batched("inputs_changed 2-param (changed)", || {
        if ic2.inputs_changed(&ic_world) { 1 } else { 0 }
    });

    bench_batched("inputs_changed 4-param (changed)", || {
        if ic4.inputs_changed(&ic_world) { 1 } else { 0 }
    });

    bench_batched("inputs_changed 8-param (changed)", || {
        if ic8.inputs_changed(&ic_world) { 1 } else { 0 }
    });

    // Advance tick so inputs are stale.
    ic_world.next_sequence();

    bench_batched("inputs_changed 1-param (stale)", || {
        if ic1.inputs_changed(&ic_world) { 1 } else { 0 }
    });

    bench_batched("inputs_changed 2-param (stale)", || {
        if ic2.inputs_changed(&ic_world) { 1 } else { 0 }
    });

    bench_batched("inputs_changed 4-param (stale)", || {
        if ic4.inputs_changed(&ic_world) { 1 } else { 0 }
    });

    bench_batched("inputs_changed 8-param (stale)", || {
        if ic8.inputs_changed(&ic_world) { 1 } else { 0 }
    });

    println!();
}

pub unsafe fn get<T: 'static>(&self, id: ResourceId) -> &T

Fetch a shared reference to a resource by pre-validated index.

Safety

• id must have been returned by WorldBuilder::register for the same builder that produced this container.
• T must be the same type that was registered at this id.
• The caller must ensure no mutable reference to this resource exists.

pub unsafe fn get_mut<T: 'static>(&self, id: ResourceId) -> &mut T

Fetch a mutable reference to a resource by pre-validated index.

Takes &self — the container structure is frozen, but individual resources have interior mutability via raw pointers. Sound because callers (single-threaded sequential dispatch) uphold no-aliasing.

Safety

• id must have been returned by WorldBuilder::register for the same builder that produced this container.
• T must be the same type that was registered at this id.
• The caller must ensure no other reference (shared or mutable) to this resource exists.

pub unsafe fn get_ptr(&self, id: ResourceId) -> *mut u8

Fetch a raw pointer to a resource by pre-validated index.

Intended for macro-generated dispatch code that needs direct pointer access.

Safety

• id must have been returned by WorldBuilder::register for the same builder that produced this container.

Trait Implementations

impl Send for World