dispatch-core 0.3.0

A small, no_std, table-driven dispatch core
Documentation
# dispatch-core

[![Crates.io](https://img.shields.io/crates/v/dispatch-core.svg)](https://crates.io/crates/dispatch-core)
[![Documentation](https://docs.rs/dispatch-core/badge.svg)](https://docs.rs/dispatch-core)
[![CI](https://github.com/griskzx/dispatch-core/actions/workflows/ci.yml/badge.svg)](https://github.com/griskzx/dispatch-core/actions/workflows/ci.yml)
[![License](https://img.shields.io/crates/l/dispatch-core.svg)](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;

let response = dispatcher.dispatch(&2, |route, _command| {
    handled += 1;
    Ok::<_, Infallible>(route.response)
});

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,
);

let selected_command = dispatcher.dispatch(&1, |_route, command| {
    Ok::<_, Infallible>(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
dispatcher.dispatch(input, |item, input| item.execute(input))
```

or an application-specific pipeline:

```text
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`](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.