ratio_reactor/lib.rs
1//! # Ratio Reactor
2//!
3//! Ratio Reactor contains several structs and traits to quickly set up a queueing job shop reactors
4//! with different queuing strategies and means of keeping track of the reactor's status.
5//!
6//! ## What is a Reactor?
7//!
8//! What does a reactor do? A reactor is a bi-directional WebWorker implementation that can send and
9//! receive messages and perform actions off of the main thread in your browser. Or in
10//! [yew-agent](https://docs.rs/yew-agent/latest/yew_agent/)'s terms:
11//!
12//! > A kind of agent that can send many inputs and receive many outputs over a single bridge.
13//!
14//! Which means you can depend on the outputs of such a worker in your frontend, too!
15//!
16//! ## Why queueing strategies?
17//!
18//! A typical workflow would be to write your Yew app as usual, but implement certain heavy tasks in
19//! a WebWorker. You might want to just do "calculate-thing" as a "oneshot" that updates your state,
20//! but what happens when you fire many such messages shortly after each other? Which call or result
21//! is "the boss"? What is returned and should you update the UI for every call?
22//!
23//! And what if you would like to know what your worker's status is display that in your app? Is the
24//! worker busy? How busy? Many jobs waiting or just a single one? Can you categorize jobs, too?
25//!
26//! ## Queueing strategies
27//!
28//! The following strategies are supported as of now:
29//!
30//! - FIFO queue
31//! - All jobs are executed in the order of arrival
32//! - Skip waiting
33//! - New jobs that arrive while executing replace any waiting job
34//! - Immediate switching
35//! - Quit current job on new arrival and work on that
36//!
37//! ## Categorized keys
38//!
39//! Both the FIFO and skip queue support "categorized keys", meaning that you can apply these
40//! strategies "in-parallel" for different kinds of jobs and priorities. Code execution won't be
41//! truly parallel per-se, but the reactor will keep a record of the strategy for each unique key
42//! such that all jobs tagged with a certain key follow the proposed strategy independent from each
43//! other.
44//!
45//! The provided implementations of these keyed queueing strategies make use of the
46//! [`BTreeMap`](std::collections::BTreeMap) which results in "prioritized" categories, where the
47//! first key (i.e. the keys are sorted by their `Ord` and not by insertion order) has the highest
48//! priority and will be processed first.
49//!
50//! ## Examples
51//!
52//! For examples, please take a look at the ones in the [GitLab
53//! repository](https://gitlab.com/ratio-case-os/rust/ratio-reactor/-/tree/main/examples)
54//!
55//! ## License
56//!
57//! This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
58//! If a copy of the MPL was not distributed with this file,
59//! You can obtain one at <https://mozilla.org/MPL/2.0/>.
60//!
61//! **Code examples both in the docstrings and rendered documentation are free to use.**
62
63pub mod fifo;
64pub mod immediate;
65pub mod key;
66#[cfg(feature = "leptos")]
67pub mod leptos;
68pub mod poll;
69pub mod reactor;
70pub mod relay;
71pub mod skip;
72pub mod status;