Skip to main content

Crate dispatch_core

Crate dispatch_core 

Source
Expand description

§dispatch-core

Crates.io Documentation CI 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:

[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

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:

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:

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:

§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.

Structs§

Dispatcher
A dispatcher backed by a borrowed table and a matching strategy.

Enums§

DispatchError
An error raised while dispatching an input.

Traits§

Matcher
Determines whether an item accepts an input.