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 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:

[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

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:

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 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.
  • 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:

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§

Handler
Executes a selected dispatch-table item.
Matcher
Determines whether an item accepts an input.