diff --git a/src/store.rs b/src/store.rs index 60ec1ebd..6c80dfc5 100644 --- a/src/store.rs +++ b/src/store.rs @@ -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 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>; + + /// 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 where S: State + Clone + Send + Sync, @@ -52,6 +59,10 @@ where S: State + 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, mut interrupt_rx: broadcast::Receiver>, ) -> anyhow::Result> { - // 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) { diff --git a/src/task.rs b/src/task.rs index 1f225d14..4bd9087f 100644 --- a/src/task.rs +++ b/src/task.rs @@ -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

where @@ -13,6 +15,7 @@ where User { payload: Option

}, } +/// The `Terminator` wraps a broadcast channel and can send an interrupt messages. #[derive(Debug, Clone)] pub struct Terminator

where @@ -25,10 +28,12 @@ impl

Terminator

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>) -> Self { Self { interrupt_tx } } + /// Send interrupt message to the broadcast channel. pub fn terminate(&mut self, interrupted: Interrupted

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

(mut terminator: Terminator

) 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

() -> (Terminator

, broadcast::Receiver>) where P: Clone + Send + Sync + Debug + 'static, diff --git a/src/terminal.rs b/src/terminal.rs index e5faf2e8..53e2cc37 100644 --- a/src/terminal.rs +++ b/src/terminal.rs @@ -91,6 +91,7 @@ impl ratatui::backend::Backend for TermionBackendExt { } } +/// Setup a `Terminal` with inline viewport using the `termion` backend. pub fn setup(height: usize) -> anyhow::Result> { let stdout = io::stdout().into_raw_mode()?; let options = TerminalOptions { @@ -103,11 +104,15 @@ pub fn setup(height: usize) -> anyhow::Result> { )?) } +/// Restore the `Terminal` on quit. pub fn restore(terminal: &mut Terminal) -> 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 { let (tx, rx) = mpsc::unbounded_channel(); let events_tx = tx.clone(); diff --git a/src/ui.rs b/src/ui.rs index 1038ddd0..fc3e7af9 100644 --- a/src/ui.rs +++ b/src/ui.rs @@ -27,11 +27,17 @@ type Backend = TermionBackendExt>; 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 { action_tx: mpsc::UnboundedSender, } impl Frontend { + /// Create a new `Frontend` storing the sending end of a message channel. pub fn new() -> (Self, UnboundedSender, UnboundedReceiver) { let (action_tx, action_rx) = mpsc::unbounded_channel(); @@ -44,6 +50,20 @@ impl Frontend { ) } + /// 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( self, root: Option, diff --git a/src/ui/widget.rs b/src/ui/widget.rs index 0f331414..54db68e7 100644 --- a/src/ui/widget.rs +++ b/src/ui/widget.rs @@ -63,9 +63,9 @@ pub trait View { /// 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); }