Struct Command

pub struct Command<Effect, Event> { /* private fields */ }

Implementations

impl<Effect, Event> Command<Effect, Event>

pub fn was_aborted(&self) -> bool

impl<Effect, Event> Command<Effect, Event>

where Effect: Send + 'static, Event: Send + 'static,

pub fn new<F, Fut>(create_task: F) -> Self

where F: FnOnce(CommandContext<Effect, Event>) -> Fut, Fut: Future<Output = ()> + Send + 'static,

Create a new command orchestrating effects with async Rust. This is the lowest level API to create a Command if you need full control over its execution. In most cases you will more likely want to create Commands with capabilities, and using the combinator APIs (and and all) to orchestrate them.

The create_task closure receives a CommandContext that it can use to send shell requests, events back to the app, and to spawn additional tasks. The closure is expected to return a future which becomes the command’s main asynchronous task.

Panics

If we could not make the task ready because the ready channel was disconnected.

pub fn done() -> Self

Create an empty, completed Command. This is useful as a return value from update if there are no side-effects to perform.

pub fn from<Ef, Ev>(subcmd: Command<Ef, Ev>) -> Self

where Ef: Send + 'static + Into<Effect> + Unpin, Ev: Send + 'static + Into<Event> + Unpin, Effect: Unpin, Event: Unpin,

Create a command from another command with compatible Effect and Event types

pub fn into<Ef, Ev>(self) -> Command<Ef, Ev>

where Ef: Send + 'static + Unpin, Ev: Send + 'static + Unpin, Effect: Unpin + Into<Ef>, Event: Unpin + Into<Ev>,

Turn the command into another command with compatible Effect and Event types

pub fn event(event: Event) -> Self

Create a Command which dispatches an event and terminates. This is an alternative to calling update recursively. The only difference is that the two update calls will be visible to Crux and can show up in logs or any tooling. The trade-off is that the event is not guaranteed to dispatch instantly - another update call which is already scheduled may happen first.

pub fn notify_shell<Op>( operation: Op, ) -> NotificationBuilder<Effect, Event, impl Future<Output = ()>>

where Op: Operation, Effect: From<Request<Op>>,

Start a creation of a Command which sends a notification to the shell with a provided operation.

Returns a NotificationBuilder which can be converted into a Command directly.

In an async context, NotificationBuilder can be turned into a future that resolves to the operation output type.

pub fn request_from_shell<Op>( operation: Op, ) -> RequestBuilder<Effect, Event, impl Future<Output = Op::Output>>

where Op: Operation, Effect: From<Request<Op>>,

Start a creation of a Command which sends a one-time request to the shell with a provided operation.

Returns a RequestBuilder, which can be converted into a Command directly, or chained with another command builder using .then.

In an async context, RequestBuilder can be turned into a future that resolves to the operation output type.

pub fn stream_from_shell<Op>( operation: Op, ) -> StreamBuilder<Effect, Event, impl Stream<Item = Op::Output>>

where Op: Operation, Effect: From<Request<Op>>,

Start a creation of a Command which sends a stream request to the shell with a provided operation.

Returns a StreamBuilder, which can be converted into a Command directly, or chained with a RequestBuilder builder using .then.

In an async context, StreamBuilder can be turned into a stream that with the operation output type as item.

pub fn is_done(&mut self) -> bool

Run the effect state machine until it settles, then return true if there is any more work to do - tasks to run or events or effects to receive

pub fn effects(&mut self) -> impl Iterator<Item = Effect> + '_

Run the effect state machine until it settles and return an iterator over the effects

pub fn events(&mut self) -> impl Iterator<Item = Event> + '_

Run the effect state machine until it settles and return an iterator over the events

pub fn then(self, other: Self) -> Self

where Effect: Unpin, Event: Unpin,

Create a command running self and the other command in sequence

pub fn and(self, other: Self) -> Self

where Effect: Unpin, Event: Unpin,

Convenience for Command::all which runs another command concurrently with this one

pub fn all<I>(commands: I) -> Self

where I: IntoIterator<Item = Self>, Effect: Unpin, Event: Unpin,

Create a command running a number of commands concurrently

pub fn map_effect<F, NewEffect>(self, map: F) -> Command<NewEffect, Event>

where F: Fn(Effect) -> NewEffect + Send + Sync + 'static, NewEffect: Send + Unpin + 'static, Effect: Unpin, Event: Unpin,

Map effects requested as part of this command to a different effect type.

This is useful when composing apps to convert a command from a child app to a command of the parent app.

pub fn map_event<F, NewEvent>(self, map: F) -> Command<Effect, NewEvent>

where F: Fn(Event) -> NewEvent + Send + Sync + 'static, NewEvent: Send + Unpin + 'static, Effect: Unpin, Event: Unpin,

Map events sent as part of this command to a different effect type

This is useful when composing apps to convert a command from a child app to a command of the parent app.

pub fn spawn<F, Fut>(&mut self, create_task: F)

where F: FnOnce(CommandContext<Effect, Event>) -> Fut, Fut: Future<Output = ()> + Send + 'static,

Spawn an additional task on the command. The task will execute concurrently with existing tasks

The create_task closure receives a CommandContext that it can use to send shell requests, events back to the app, and to spawn additional tasks. The closure is expected to return a future.

pub fn abort_handle(&self) -> AbortHandle

Returns an abort handle which can be used to remotely terminate a running Command and all its subtask.

This is specifically useful for cancelling subscriptions and long running effects which may get superseded, like timers

impl<Effect, Event> Command<Effect, Event>

where Effect: Send + 'static, Event: Send + 'static,

pub fn expect_one_effect(&mut self) -> Effect

Assert that the Command contains exactly one effect and zero events, and return the effect

Panics

Panics if the command does not contain exactly one effect, or contains any events.

Trait Implementations

impl<Effect, Event, Task> From<NotificationBuilder<Effect, Event, Task>> for Command<Effect, Event>

where Effect: Send + 'static, Event: Send + 'static, Task: Future<Output = ()> + Send + 'static,

fn from(value: NotificationBuilder<Effect, Event, Task>) -> Self

Converts to this type from the input type.

impl<Effect, Event> FromIterator<Command<Effect, Event>> for Command<Effect, Event>

where Effect: Send + Unpin + 'static, Event: Send + Unpin + 'static,

fn from_iter<I: IntoIterator<Item = Command<Effect, Event>>>(iter: I) -> Self

Creates a value from an iterator.

impl<Effect, Event> Stream for Command<Effect, Event>

where Effect: Unpin + Send + 'static, Event: Unpin + Send + 'static,

type Item = CommandOutput<Effect, Event>

Values yielded by the stream.

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.