Struct Subscription 

pub struct Subscription<Message> { /* private fields */ }

The sources an application wants to hear from, for as long as it keeps declaring them.

Nothing reaches update from a source the application did not declare — terminal input included. After each update the runtime reconciles the declaration against what it is running: a declared source whose Key is already running keeps running, one whose key is not running starts, and a running one whose key is no longer declared stops.

The function each constructor takes turns the source’s own value into the application’s message; the runtime does not know that type and cannot deliver without one. That function is not part of a source’s identity, so a source declared again keeps running and passes its messages through the most recent declaration’s function from then on.

use std::time::Duration;

use urushi_tui_app::{Input, Subscription};

enum Message {
    Input(Input),
    Tick,
}

let subscription = Subscription::batch([
    Subscription::input(Message::Input),
    Subscription::interval("clock", Duration::from_secs(1), |_| Message::Tick),
]);

Implementations

impl<Message> Subscription<Message>

pub fn none() -> Self

No source.

pub fn input<F>(f: F) -> Self

where F: Fn(Input) -> Message + Send + Sync + 'static,

Terminal key and text input.

Input is a subscription rather than a method the runtime always calls, so a program that must not receive input in some state — while an external editor owns the terminal, say — declares none in that state.

pub fn surface<F>(f: F) -> Self

where F: Fn(Surface) -> Message + Send + Sync + 'static,

Observations of the surface the application draws on.

pub fn interval<F>(key: impl Into<Key>, period: Duration, f: F) -> Self

where F: Fn(Instant) -> Message + Send + Sync + 'static,

A timer that fires every period, for as long as it is declared.

An interval is the one runtime source an application can want more than one of, so it names its own: two timers of one period are two timers when their keys differ. Declaring the same key with a different period restarts that timer at the new period.

A timer that should fire once is Effect::after rather than an interval the application stops declaring.

pub fn signal<F>(signal: Signal, f: F) -> Self

where F: Fn(Signal) -> Message + Send + Sync + 'static,

One process signal.

A handler is installed only for a signal that is declared.

pub fn terminal_errors<F>(f: F) -> Self

where F: Fn(Error) -> Message + Send + Sync + 'static,

Failures the terminal reports while drawing.

A draw that fails ends the run unless this is declared. With it, the failure arrives as a message, the frame that failed is not committed, and the application decides what to do — ignore it, record it, save and shut down.

pub fn stream<S>(key: impl Into<Key>, stream: S) -> Self

where S: Stream<Item = Message> + Send + 'static, Message: Send + 'static,

An application-defined source that is a stream, under the default admission.

pub fn stream_with<S>( key: impl Into<Key>, admission: Admission, stream: S, ) -> Self

where S: Stream<Item = Message> + Send + 'static, Message: Send + 'static,

An application-defined source that is a stream, under admission.

pub fn run<F, Fut>(key: impl Into<Key>, f: F) -> Self

where F: FnOnce(Sender<Message>) -> Fut + Send + 'static, Fut: Future<Output = ()> + Send + 'static, Message: Send + 'static,

An application-defined asynchronous source, under the default admission.

pub fn run_with<F, Fut>(key: impl Into<Key>, admission: Admission, f: F) -> Self

where F: FnOnce(Sender<Message>) -> Fut + Send + 'static, Fut: Future<Output = ()> + Send + 'static, Message: Send + 'static,

An application-defined asynchronous source, under admission.

pub fn run_blocking<F>(key: impl Into<Key>, f: F) -> Self

where F: FnOnce(Sender<Message>) + Send + 'static, Message: Send + 'static,

An application-defined blocking source, run on its own thread, under the default admission.

pub fn run_blocking_with<F>( key: impl Into<Key>, admission: Admission, f: F, ) -> Self

where F: FnOnce(Sender<Message>) + Send + 'static, Message: Send + 'static,

An application-defined blocking source, run on its own thread, under admission.

pub fn batch(subscriptions: impl IntoIterator<Item = Self>) -> Self

Several sources.

pub fn map<To>( self, f: impl Fn(Message) -> To + Send + Sync + 'static, ) -> Subscription<To>

where Message: Send + 'static, To: Send + 'static,

The same sources with their messages passed through f.

A parent program declares a child’s subscriptions mapped into its own message, so the child stays a program of its own.

Trait Implementations

impl<Message> Debug for Subscription<Message>

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<Message> Default for Subscription<Message>

fn default() -> Self

Returns the “default value” for a type.