# 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 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:
```toml
[dependencies]
dispatch-core = "0.3.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. passes the selected item and original input to the executor closure;
4. 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
```rust
use core::convert::Infallible;
use dispatch_core::{Dispatcher, Matcher};
struct Route {
command: u8,
response: u8,
}
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 handled = 0_u8;
assert_eq!(response, Ok(20));
assert_eq!(handled, 1);
```
Matchers can also be closures:
```rust
use core::convert::Infallible;
use dispatch_core::Dispatcher;
struct Route {
command: u8,
}
let routes = [Route { command: 1 }];
let dispatcher = Dispatcher::new(
&routes,
|route: &Route, command: &u8| route.command == *command,
);
assert_eq!(selected_command, Ok(&1));
```
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:
```text
or an application-specific pipeline:
```text
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`](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.
- 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:
```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.