Crate korhah

korhah

korhah is a minimal & extensible reactive event system.

At its most basic, it allows users to register callback functions and emit arbitrary custom events which will trigger those functions.

It can also act as an object store, whose contents are accessible from within registered callback functions as well as from outside the system.

To keep it minimal, only basic CRUD operations are provided along with signal-y behaviour via automatic dependency-tracking.

To make it extensible, the built-in CRUD operations emit events that can be hooked into.

Example Usage

let mut system = korhah::System::default();

// create a simple variable in the reactive system
let a = system.create(|_, _| 0).expect("no cancelling listeners registered");
// create a signal-y variable that depends on `a`
let b = system.create(move |s, _| {
    // the dependency on `a` is automatically tracked here
    let a = s.read(a, |v| *v)
        .expect("no cancelling listeners registered")
        .expect("`a` exists");
    // subsequent updates to `a` will recompute `b` according to this formula
    a + 1
}).expect("no cancelling listeners registered");

// we can emit *any* 'static type we like as an event
struct CustomEvent {
    n: i32,
}

// listen for our custom event being emitted in a "global" scope
// (the "global" scope being due to specifying a `None` target)
system.listen(None, move |s, e: &CustomEvent, _, _| {
    // we'll update `a` to the associated event info
    // (note that this should automatically update `b` too)
    _ = s.update(a, |v| *v = e.n);
});

assert_eq!(Ok(Some(0)), system.read(a, |v| *v));
assert_eq!(Ok(Some(1)), system.read(b, |v| *v));

// emit our custom event
_ = system.emit(None, &CustomEvent { n: 42 });

assert_eq!(Ok(Some(42)), system.read(a, |v| *v));
assert_eq!(Ok(Some(43)), system.read(b, |v| *v));

no_std

This crate is compatible with no_std environments, requiring only the alloc crate.

(Un)Sync

This crate can be used in both single-threaded and multi-threaded environments.
In the spirit of cargo features being additive, the stricter Send + Sync bounds of a multi-threaded environment are assumed by default for variable types and callback types, and these bounds can be relaxed for single-threaded environments via the unsync feature.

MSRV

The minimum supported Rust version is 1.63.0.

---

Modules

events

Events that are emitted as a result of built-in CRUD actions

Structs

Listener

 A typed handle to a listener in the reactive system

System

The reactive system

Variable

A typed handle to a variable belonging to the reactive system

Votes

Represents the consensus among event handlers as to whether or not the effects from their corresponding event should be followed through.
Effects of built-in events are followed through if the number of votes to proceed >= the number of votes to cancel.
Custom events decide their own criteria for acting on these results, if at all.

Enums

Vote

Represents a certain event handler’s preference as to whether or not the effects from its corresponding event should be followed through