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 dispatcher designed for no_std environments. It selects the first matching item from a table and runs it through explicit before/after middleware hooks.

The crate deliberately does not own application state. A higher-level crate can build a state machine on top by dispatching (state, event) inputs and committing the returned next state only after dispatch succeeds.

§Installation

Add the crate to your project:

[dependencies]
dispatch-core = "0.1.0"

§Execution model

For each call, the dispatcher:

  1. selects the first matching table item;
  2. runs the middleware’s before hook;
  3. invokes the selected handler;
  4. runs the middleware’s after hook.

Processing stops at the first error. Middleware receives an immutable input, so it cannot invalidate a match after selection. The after hook can modify a successful output.

§Example

use core::convert::Infallible;
use dispatch_core::{Dispatcher, Handler, Matcher, NoopMiddleware};

struct Route {
    command: u8,
    response: u8,
}

impl Handler for Route {
    type Input = u8;
    type Output = u8;
    type Error = Infallible;

    fn handle(&self, _input: &Self::Input) -> Result<Self::Output, Self::Error> {
        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 mut dispatcher = Dispatcher::new(CommandMatcher, NoopMiddleware);

assert_eq!(dispatcher.dispatch(&routes, &2), Ok(20));

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

§Complete example

See examples/command_dispatch.rs for a complete command-routing example with authorization before the handler and output auditing after it succeeds. Run it with:

cargo run --example command_dispatch

§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 that owns the components used to select and wrap a handler.
NoopMiddleware
Middleware that performs no work.

Enums§

DispatchError
An error raised while dispatching an input.

Traits§

Handler
Handles a dispatched input.
Matcher
Selects table items for an input.
Middleware
Runs logic immediately before and after the selected handler.

Functions§

dispatch
Dispatches input to the first matching item in table.