mirror of
https://seed.radicle.dev/rad:z39mP9rQAaGmERfUMPULfPUi473tY.git
synced 2026-11-21 10:30:48 +08:00
lib: Add doc comments
This commit is contained in:
+15
-4
@@ -11,15 +11,22 @@ use super::task::{Interrupted, Terminator};
|
||||
|
||||
const STORE_TICK_RATE: Duration = Duration::from_millis(1000);
|
||||
|
||||
/// The `State` known to the application store. It handles user-defined
|
||||
/// application messages as well as ticks.
|
||||
pub trait State<A, P>
|
||||
where
|
||||
P: Clone + Debug + Send + Sync,
|
||||
{
|
||||
fn tick(&self);
|
||||
|
||||
/// Handle a user-defined application message and return an `Exit` object
|
||||
/// in case the received message requested the application to also quit.
|
||||
fn handle_action(&mut self, action: A) -> Option<Exit<P>>;
|
||||
|
||||
/// Handle recurring tick.
|
||||
fn tick(&self);
|
||||
}
|
||||
|
||||
/// The `Store` updates the applications' state concurrently. It handles
|
||||
/// messages coming from the frontend and updates the state accordingly.
|
||||
pub struct Store<A, S, P>
|
||||
where
|
||||
S: State<A, P> + Clone + Send + Sync,
|
||||
@@ -52,6 +59,10 @@ where
|
||||
S: State<A, P> + Clone + Debug + Send + Sync + 'static,
|
||||
P: Clone + Debug + Send + Sync + 'static,
|
||||
{
|
||||
/// By calling `main_loop`, the store will wait for new messages coming
|
||||
/// from the frontend and update the applications' state accordingly. It will
|
||||
/// also tick with the defined `STORE_TICK_RATE`.
|
||||
/// Updated states are then being send to the state message channel.
|
||||
pub async fn main_loop(
|
||||
self,
|
||||
mut state: S,
|
||||
@@ -59,14 +70,14 @@ where
|
||||
mut action_rx: UnboundedReceiver<A>,
|
||||
mut interrupt_rx: broadcast::Receiver<Interrupted<P>>,
|
||||
) -> anyhow::Result<Interrupted<P>> {
|
||||
// the initial state once
|
||||
// Send the initial state once
|
||||
self.state_tx.send(state.clone())?;
|
||||
|
||||
let mut ticker = tokio::time::interval(STORE_TICK_RATE);
|
||||
|
||||
let result = loop {
|
||||
tokio::select! {
|
||||
// Handle the actions coming from the UI
|
||||
// Handle the actions coming from the frontend
|
||||
// and process them to do async operations
|
||||
Some(action) = action_rx.recv() => {
|
||||
if let Some(exit) = state.handle_action(action) {
|
||||
|
||||
+7
-1
@@ -4,6 +4,8 @@ use std::fmt::Debug;
|
||||
use tokio::signal::unix::signal;
|
||||
use tokio::sync::broadcast;
|
||||
|
||||
/// An `Interrupt` message that is produced by either an OS signal (e.g. kill)
|
||||
/// or the user by requesting the application to close.
|
||||
#[derive(Debug, Clone)]
|
||||
pub enum Interrupted<P>
|
||||
where
|
||||
@@ -13,6 +15,7 @@ where
|
||||
User { payload: Option<P> },
|
||||
}
|
||||
|
||||
/// The `Terminator` wraps a broadcast channel and can send an interrupt messages.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct Terminator<P>
|
||||
where
|
||||
@@ -25,10 +28,12 @@ impl<P> Terminator<P>
|
||||
where
|
||||
P: Clone + Send + Sync + Debug + 'static,
|
||||
{
|
||||
/// Create a `Terminator` that stores the sending end of a broadcast channel.
|
||||
pub fn new(interrupt_tx: broadcast::Sender<Interrupted<P>>) -> Self {
|
||||
Self { interrupt_tx }
|
||||
}
|
||||
|
||||
/// Send interrupt message to the broadcast channel.
|
||||
pub fn terminate(&mut self, interrupted: Interrupted<P>) -> anyhow::Result<()> {
|
||||
self.interrupt_tx.send(interrupted)?;
|
||||
|
||||
@@ -36,6 +41,7 @@ where
|
||||
}
|
||||
}
|
||||
|
||||
/// Receive `SIGINT` and call terminator which sends the interrupt message to its broadcast channel.
|
||||
#[cfg(unix)]
|
||||
async fn terminate_by_unix_signal<P>(mut terminator: Terminator<P>)
|
||||
where
|
||||
@@ -51,7 +57,7 @@ where
|
||||
.expect("failed to send interrupt signal");
|
||||
}
|
||||
|
||||
// create a broadcast channel for retrieving the application kill signal
|
||||
/// Create a broadcast channel and spawn a task for retrieving the applications' kill signal.
|
||||
pub fn create_termination<P>() -> (Terminator<P>, broadcast::Receiver<Interrupted<P>>)
|
||||
where
|
||||
P: Clone + Send + Sync + Debug + 'static,
|
||||
|
||||
@@ -91,6 +91,7 @@ impl<W: Write> ratatui::backend::Backend for TermionBackendExt<W> {
|
||||
}
|
||||
}
|
||||
|
||||
/// Setup a `Terminal` with inline viewport using the `termion` backend.
|
||||
pub fn setup(height: usize) -> anyhow::Result<Terminal<Backend>> {
|
||||
let stdout = io::stdout().into_raw_mode()?;
|
||||
let options = TerminalOptions {
|
||||
@@ -103,11 +104,15 @@ pub fn setup(height: usize) -> anyhow::Result<Terminal<Backend>> {
|
||||
)?)
|
||||
}
|
||||
|
||||
/// Restore the `Terminal` on quit.
|
||||
pub fn restore(terminal: &mut Terminal<Backend>) -> anyhow::Result<()> {
|
||||
terminal.clear()?;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Spawn one thread that polls `stdin` for new user input and another thread
|
||||
/// that polls UNIX signals, e.g. `SIGWINCH` when the terminal window size is
|
||||
/// being changed.
|
||||
pub fn events() -> mpsc::UnboundedReceiver<Event> {
|
||||
let (tx, rx) = mpsc::unbounded_channel();
|
||||
let events_tx = tx.clone();
|
||||
|
||||
@@ -27,11 +27,17 @@ type Backend = TermionBackendExt<RawTerminal<io::Stdout>>;
|
||||
const RENDERING_TICK_RATE: Duration = Duration::from_millis(250);
|
||||
const INLINE_HEIGHT: usize = 20;
|
||||
|
||||
/// The `Frontend` runs an applications' view concurrently. It handles
|
||||
/// terminal events as well as state updates and renders the view accordingly.
|
||||
///
|
||||
/// Once created and run with `main_loop`, the `Frontend` will wait for new messages
|
||||
/// being sent on either the terminal event, the state or the interrupt message channel.
|
||||
pub struct Frontend<A> {
|
||||
action_tx: mpsc::UnboundedSender<A>,
|
||||
}
|
||||
|
||||
impl<A> Frontend<A> {
|
||||
/// Create a new `Frontend` storing the sending end of a message channel.
|
||||
pub fn new() -> (Self, UnboundedSender<A>, UnboundedReceiver<A>) {
|
||||
let (action_tx, action_rx) = mpsc::unbounded_channel();
|
||||
|
||||
@@ -44,6 +50,20 @@ impl<A> Frontend<A> {
|
||||
)
|
||||
}
|
||||
|
||||
/// By calling `main_loop`, the `Frontend` will wait for new messages being sent
|
||||
/// on either the terminal event, the state or the interrupt message channel.
|
||||
/// After all, it will draw the (potentially) updated root widget.
|
||||
///
|
||||
/// Terminal event messages are being sent by a thread polling `stdin` for new user input
|
||||
/// and another thread polling UNIX signals, e.g. `SIGWINCH` when the terminal
|
||||
/// window size is being changed. Terminal events are then passed to the root widget
|
||||
/// of the application.
|
||||
///
|
||||
/// State messages are being sent by the applications' `Store`. Received state updates
|
||||
/// will be passed to the root widget as well.
|
||||
///
|
||||
/// Interrupt messages are being sent to broadcast channel for retrieving the
|
||||
/// application kill signal.
|
||||
pub async fn main_loop<S, W, P>(
|
||||
self,
|
||||
root: Option<W>,
|
||||
|
||||
+2
-2
@@ -63,9 +63,9 @@ pub trait View<S, A> {
|
||||
/// the type of `state`. These can use widgets from the library that do not know the
|
||||
/// type of `state`.
|
||||
///
|
||||
/// If `on_update` is set, implementators of this function should call it to
|
||||
/// If `on_update` is set, implementations of this function should call it to
|
||||
/// construct and update the internal props. If it is not set, app widgets can construct
|
||||
/// prosp directly via their state converters, whereas library widgets can just fallback
|
||||
/// props directly via their state converters, whereas library widgets can just fallback
|
||||
/// to their current props.
|
||||
fn update(&mut self, state: &S);
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user