# dispatch-core
[](https://crates.io/crates/dispatch-core)
[](https://docs.rs/dispatch-core)
[](https://github.com/griskzx/dispatch-core/actions/workflows/ci.yml)
[](https://github.com/griskzx/dispatch-core#license)
`dispatch-core` is a small, allocation-free, table-driven dispatcher for
`no_std` environments. It borrows a dispatch table, selects its first matching
item, and executes that item's handler with an explicit mutable context.
The crate deliberately does not provide middleware, application state
ownership, transactions, asynchronous execution, or dynamic route
registration. Those policies can be built around the small selection and
execution core.
## Installation
Add the crate to your project:
```toml
[dependencies]
dispatch-core = "0.2.0"
```
## Execution model
For each call, the dispatcher:
1. scans the borrowed table from beginning to end;
2. selects the first item accepted by the matcher;
3. invokes the selected item's handler;
4. returns the handler output or a structured error.
Table order defines priority. Matching and input access are immutable. Runtime
state, services, buffers, and device handles belong in the mutable context.
Context changes and other side effects are not rolled back when a handler
returns an error.
## Example
```rust
use core::convert::Infallible;
use dispatch_core::{Dispatcher, Handler, Matcher};
struct Route {
command: u8,
response: u8,
}
#[derive(Default)]
struct Context {
handled: u8,
}
impl Handler for Route {
type Input = u8;
type Context = Context;
type Output = u8;
type Error = Infallible;
fn handle(
&self,
_input: &Self::Input,
context: &mut Self::Context,
) -> Result<Self::Output, Self::Error> {
context.handled += 1;
Ok(self.response)
}
}
struct CommandMatcher;
impl Matcher<Route, u8> for CommandMatcher {
fn matches(&self, route: &Route, command: &u8) -> bool {
route.command == *command
}
}
let routes = [
Route { command: 1, response: 10 },
Route { command: 2, response: 20 },
];
let dispatcher = Dispatcher::new(&routes, CommandMatcher);
let mut context = Context::default();
assert_eq!(dispatcher.dispatch(&2, &mut context), Ok(20));
assert_eq!(context.handled, 1);
```
Matchers can also be closures:
```rust
# use core::convert::Infallible;
# use dispatch_core::{Dispatcher, Handler};
# struct Route { command: u8 }
# impl Handler for Route {
# type Input = u8;
# type Context = ();
# type Output = u8;
# type Error = Infallible;
# fn handle(&self, input: &u8, _context: &mut ()) -> Result<u8, Infallible> {
# Ok(*input)
# }
# }
let routes = [Route { command: 1 }];
let dispatcher = Dispatcher::new(
&routes,
|route: &Route, input: &u8| route.command == *input,
);
assert_eq!(dispatcher.dispatch(&1, &mut ()), Ok(1));
```
Use [`Dispatcher::select`] when selection is needed without execution.
## Complete example
See [`examples/command_dispatch.rs`](examples/command_dispatch.rs) for a
complete command router whose table stores handler function pointers. Run it
with:
```text
cargo run --example command_dispatch
```
## Complexity and guarantees
- Selection is a deterministic `O(n)` linear scan.
- 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.
- The dispatcher only needs a shared reference during dispatch.
- Handlers that need no runtime context can use `Context = ()`.
## Embedded build
The repository includes a convenience command for Cortex-M0 targets:
```text
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](LICENSE-APACHE));
- MIT License ([LICENSE-MIT](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](AI_DISCLOSURE.md) for the exact scope.