dispatch-core
dispatch-core is a small, allocation-free, table-driven dispatcher for
no_std environments. It borrows a table, selects its first matching item,
and delegates execution to a caller-provided closure.
The crate defines only the dispatch mechanism. It does not prescribe handler traits, context types, middleware stages, application state, transactions, asynchronous execution, or dynamic route registration.
Installation
Add the crate to your project:
[]
= "0.3.0"
Execution model
For each call, the dispatcher:
- scans the borrowed table from beginning to end;
- selects the first item accepted by the matcher;
- passes the selected item and original input to the executor closure;
- returns the executor output or a structured error.
Table order defines priority. Matching is immutable. The executor closure can capture arbitrary per-call state and borrowed resources, so execution policy does not become part of the dispatcher's type.
Example
use Infallible;
use ;
;
let routes = ;
let dispatcher = new;
let mut handled = 0_u8;
let response = dispatcher.dispatch;
assert_eq!;
assert_eq!;
Matchers can also be closures:
use Infallible;
use Dispatcher;
let routes = ;
let dispatcher = new;
let selected_command = dispatcher.dispatch;
assert_eq!;
Use [Dispatcher::select] when selection is needed without execution.
Application-defined execution
The executor closure is the extension point for application policy. It can be a direct function call:
dispatcher.dispatch(input, |item, input| item.execute(input))
or an application-specific pipeline:
dispatcher.dispatch(input, |item, input| {
prepare(item, input)?;
let output = execute(item, input)?;
finish(item, input, &output)?;
Ok(output)
})
The crate does not assign special semantics to those stages. Cleanup, rollback, and external side effects remain the caller's responsibility.
Complete example
See examples/command_dispatch.rs for a
complete command router whose table stores handler function pointers. Run it
with:
cargo run --example command_dispatch
Complexity and guarantees
- Selection is a deterministic
O(n)linear scan. - The executor runs exactly once when an item matches and never otherwise.
- No heap allocation is performed by the crate.
- The crate has no dependencies and forbids unsafe code.
- The dispatch table and input are never mutated by the dispatcher.
- Executors can capture short-lived mutable borrows without stored contexts.
- Executors can return values borrowed from the table or input.
Embedded build
The repository includes a convenience command for Cortex-M0 targets:
cargo build-thumbv6m
Normal cargo build, cargo test, and cargo clippy commands use the host
target, so the test harness remains available.
Minimum supported Rust version
dispatch-core requires Rust 1.85 or newer because it uses the Rust 2024
edition.
License
Licensed under either of the following, at your option:
- Apache License, Version 2.0 (LICENSE-APACHE);
- MIT License (LICENSE-MIT).
AI authorship disclosure
The current public-release implementation, tests, example, documentation, and release configuration were generated by OpenAI Codex under the repository owner's direction. They should not be represented as handwritten human work. See AI_DISCLOSURE.md for the exact scope.