Struct Subscription

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

A request to listen to external events.

Besides performing async actions on demand with Task, most applications also need to listen to external events passively.

A Subscription is normally provided to some runtime, like a Task, and it will generate events as long as the user keeps requesting it.

For instance, you can use a Subscription to listen to a WebSocket connection, keyboard presses, mouse events, time ticks, etc.

The Lifetime of a Subscription

Much like a Future or a [Stream], a Subscription does not produce any effects on its own. For a Subscription to run, it must be returned to the iced runtime—normally in the subscription function of an application or a daemon.

When a Subscription is provided to the runtime for the first time, the runtime will start running it asynchronously. Running a Subscription consists in building its underlying [Stream] and executing it in an async runtime.

Therefore, you can think of a Subscription as a “stream builder”. It simply represents a way to build a certain [Stream] together with some way to identify it.

Identification is important because when a specific Subscription stops being returned to the iced runtime, the runtime will kill its associated [Stream]. The runtime uses the identity of a Subscription to keep track of it.

This way, iced allows you to declaratively subscribe to particular streams of data temporarily and whenever necessary.

use iced::time::{self, Duration, Instant};
use iced::Subscription;

struct State {
    timer_enabled: bool,
}

fn subscription(state: &State) -> Subscription<Instant> {
    if state.timer_enabled {
        time::every(Duration::from_secs(1))
    } else {
        Subscription::none()
    }
}

Implementations

impl<T> Subscription<T>

pub fn none() -> Self

Returns an empty Subscription that will not produce any output.

pub fn run<S>(builder: fn() -> S) -> Self

where S: Stream<Item = T> + MaybeSend + 'static, T: 'static,

Returns a Subscription that will call the given function to create and asynchronously run the given [Stream].

Creating an asynchronous worker with bidirectional communication

You can leverage this helper to create a Subscription that spawns an asynchronous worker in the background and establish a channel of communication with an iced application.

You can achieve this by creating an mpsc channel inside the closure and returning the Sender as a Message for the Application:

use iced::futures::channel::mpsc;
use iced::futures::sink::SinkExt;
use iced::futures::Stream;
use iced::stream;
use iced::Subscription;

pub enum Event {
    Ready(mpsc::Sender<Input>),
    WorkFinished,
    // ...
}

enum Input {
    DoSomeWork,
    // ...
}

fn some_worker() -> impl Stream<Item = Event> {
    stream::channel(100, async |mut output| {
        // Create channel
        let (sender, mut receiver) = mpsc::channel(100);

        // Send the sender back to the application
        output.send(Event::Ready(sender)).await;

        loop {
            use iced_futures::futures::StreamExt;

            // Read next input sent from `Application`
            let input = receiver.select_next_some().await;

            match input {
                Input::DoSomeWork => {
                    // Do some async work...

                    // Finally, we can optionally produce a message to tell the
                    // `Application` the work is done
                    output.send(Event::WorkFinished).await;
                }
            }
        }
    })
}

fn subscription() -> Subscription<Event> {
    Subscription::run(some_worker)
}

Check out the websocket example, which showcases this pattern to maintain a WebSocket connection open.

pub fn run_with<D, S>(data: D, builder: fn(&D) -> S) -> Self

where D: Hash + 'static, S: Stream<Item = T> + MaybeSend + 'static, T: 'static,

Returns a Subscription that will create and asynchronously run the given [Stream].

Both the data and the function pointer will be used to uniquely identify the Subscription.

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

Batches all the provided subscriptions and returns the resulting Subscription.

pub fn with<A>(self, value: A) -> Subscription<(A, T)>

where T: 'static, A: Hash + Clone + Send + Sync + 'static,

Adds a value to the Subscription context.

The value will be part of the identity of a Subscription.

pub fn map<F, A>(self, f: F) -> Subscription<A>

where T: 'static, F: Fn(T) -> A + MaybeSend + Clone + 'static, A: 'static,

Transforms the Subscription output with the given function.

Panics

The closure provided must be a non-capturing closure. The method will panic in debug mode otherwise.

Trait Implementations

impl<T> Debug for Subscription<T>

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

Formats the value using the given formatter.