Struct Spinner

pub struct Spinner {
    pub tick_delay: Duration,
    pub message: String,
    pub style: SpinnerStyle,
    pub safe_output_terminal: SafeRawTerminal,
    pub shared_writer: SharedWriter,
    pub shutdown_sender: Sender<()>,
    /* private fields */
}

Fields

tick_delay: Duration

message: String

style: SpinnerStyle

safe_output_terminal: SafeRawTerminal

shared_writer: SharedWriter

shutdown_sender: Sender<()>

Implementations

impl Spinner

pub async fn try_start( spinner_message: String, tick_delay: Duration, style: SpinnerStyle, safe_output_terminal: SafeRawTerminal, shared_writer: SharedWriter, ) -> Result<Option<Spinner>>

Create a new instance of Spinner.

Returns

1. This will return an error if the task is already running.
2. If the terminal is not fully interactive then it will return None, and won’t start the task. This is when the terminal is not considered fully interactive:
   • stdout is piped, eg: echo "foo" | cargo run --example spinner.
   • or all three stdin, stdout, stderr are not is_tty, eg when running in cargo test.
3. Otherwise, it will start the task and return a Spinner instance.

More info on terminal piping:

• https://unix.stackexchange.com/questions/597083/how-does-piping-affect-stdin

Examples found in repository

examples/spinner.rs (lines 73-79)

async fn example_with_concurrent_output(style: SpinnerStyle) -> miette::Result<()> {
    let terminal_async = TerminalAsync::try_new("$ ").await?;
    let terminal_async = terminal_async.expect("terminal is not fully interactive");
    let address = "127.0.0.1:8000";
    let message_trying_to_connect = format!(
        "This is a sample indeterminate progress message: trying to connect to server on {}",
        &address
    );

    let mut shared_writer = terminal_async.clone_shared_writer();

    // Start spinner. Automatically pauses the terminal.
    let mut maybe_spinner = Spinner::try_start(
        message_trying_to_connect.clone(),
        DELAY_UNIT,
        style,
        Arc::new(StdMutex::new(stderr())),
        shared_writer.clone(),
    )
    .await?;

    // Start another task, to simulate some async work, that uses a interval to display
    // output, for a fixed amount of time, using `terminal_async.println_prefixed()`.
    let _ = try_join!(tokio::spawn(async move {
        // To calculate the delay.
        let duration = ARTIFICIAL_UI_DELAY;
        let start = Instant::now();

        // Dropping the interval cancels it.
        let mut interval = tokio::time::interval(Duration::from_millis(DELAY_MS * 5));

        loop {
            interval.tick().await;
            let elapsed = start.elapsed();
            if elapsed >= duration {
                break;
            }
            let _ = writeln!(shared_writer, "⏳foo");
        }
    }));

    // Stop spinner. Automatically resumes the terminal.
    if let Some(spinner) = maybe_spinner.as_mut() {
        spinner
            .stop("This is a sample final message for the spinner component: Connected to server")
            .await?;
    }

    tokio::time::sleep(Duration::from_millis(500)).await;

    Ok(())
}

examples/terminal_async.rs (lines 386-395)

    pub fn spawn_task_that_shows_spinner(
        shared_writer: &mut SharedWriter,
        readline: &mut Readline,
        task_name: &str,
        delay: Duration,
    ) {
        let mut interval = interval(delay);
        let mut tick_counter = 0;
        let max_tick_count = 30;

        let task_name = task_name.to_string();

        let shared_writer_clone_1 = shared_writer.clone();
        let mut shared_writer_clone_2 = shared_writer.clone();

        if readline.safe_spinner_is_active.lock().unwrap().is_some() {
            _ = writeln!(
                shared_writer,
                "Spinner is already active, can't start another one"
            );
        }

        tokio::spawn(async move {
            // Try to create and start a spinner.
            let maybe_spinner = Spinner::try_start(
                format!(
                    "{} - This is a sample indeterminate progress message",
                    task_name
                ),
                Duration::from_millis(100),
                SpinnerStyle::default(),
                Arc::new(StdMutex::new(stderr())),
                shared_writer_clone_1,
            )
            .await;

            loop {
                // Check for spinner shutdown (via interruption).
                if let Ok(Some(ref spinner)) = maybe_spinner {
                    if spinner.is_shutdown() {
                        break;
                    }
                }

                // Wait for the interval duration (one tick).
                interval.tick().await;

                // Don't print more than `max_tick_count` times.
                tick_counter += 1;
                if tick_counter >= max_tick_count {
                    break;
                }

                // Display a message at every tick.
                let _ = writeln!(
                    shared_writer_clone_2,
                    "[{task_name}] - [{tick_counter}] interval went off while spinner was spinning!"
                );
            }

            // Don't forget to stop the spinner.
            if let Ok(Some(mut spinner)) = maybe_spinner {
                let msg = format!("{} - Task ended. Resuming terminal and showing any output that was generated while spinner was active.", task_name);
                let _ = spinner.stop(msg.as_str()).await;
            }
        });
    }

pub fn is_shutdown(&self) -> bool

This is meant for the task that spawned this Spinner to check if it should shutdown, due to:

1. The user pressing Ctrl-C or Ctrl-D.
2. Or the Spinner::stop got called.

Examples found in repository

examples/terminal_async.rs (line 401)

    pub fn spawn_task_that_shows_spinner(
        shared_writer: &mut SharedWriter,
        readline: &mut Readline,
        task_name: &str,
        delay: Duration,
    ) {
        let mut interval = interval(delay);
        let mut tick_counter = 0;
        let max_tick_count = 30;

        let task_name = task_name.to_string();

        let shared_writer_clone_1 = shared_writer.clone();
        let mut shared_writer_clone_2 = shared_writer.clone();

        if readline.safe_spinner_is_active.lock().unwrap().is_some() {
            _ = writeln!(
                shared_writer,
                "Spinner is already active, can't start another one"
            );
        }

        tokio::spawn(async move {
            // Try to create and start a spinner.
            let maybe_spinner = Spinner::try_start(
                format!(
                    "{} - This is a sample indeterminate progress message",
                    task_name
                ),
                Duration::from_millis(100),
                SpinnerStyle::default(),
                Arc::new(StdMutex::new(stderr())),
                shared_writer_clone_1,
            )
            .await;

            loop {
                // Check for spinner shutdown (via interruption).
                if let Ok(Some(ref spinner)) = maybe_spinner {
                    if spinner.is_shutdown() {
                        break;
                    }
                }

                // Wait for the interval duration (one tick).
                interval.tick().await;

                // Don't print more than `max_tick_count` times.
                tick_counter += 1;
                if tick_counter >= max_tick_count {
                    break;
                }

                // Display a message at every tick.
                let _ = writeln!(
                    shared_writer_clone_2,
                    "[{task_name}] - [{tick_counter}] interval went off while spinner was spinning!"
                );
            }

            // Don't forget to stop the spinner.
            if let Ok(Some(mut spinner)) = maybe_spinner {
                let msg = format!("{} - Task ended. Resuming terminal and showing any output that was generated while spinner was active.", task_name);
                let _ = spinner.stop(msg.as_str()).await;
            }
        });
    }

pub async fn stop(&mut self, final_message: &str) -> Result<()>

Examples found in repository

examples/spinner.rs (line 105)

async fn example_with_concurrent_output(style: SpinnerStyle) -> miette::Result<()> {
    let terminal_async = TerminalAsync::try_new("$ ").await?;
    let terminal_async = terminal_async.expect("terminal is not fully interactive");
    let address = "127.0.0.1:8000";
    let message_trying_to_connect = format!(
        "This is a sample indeterminate progress message: trying to connect to server on {}",
        &address
    );

    let mut shared_writer = terminal_async.clone_shared_writer();

    // Start spinner. Automatically pauses the terminal.
    let mut maybe_spinner = Spinner::try_start(
        message_trying_to_connect.clone(),
        DELAY_UNIT,
        style,
        Arc::new(StdMutex::new(stderr())),
        shared_writer.clone(),
    )
    .await?;

    // Start another task, to simulate some async work, that uses a interval to display
    // output, for a fixed amount of time, using `terminal_async.println_prefixed()`.
    let _ = try_join!(tokio::spawn(async move {
        // To calculate the delay.
        let duration = ARTIFICIAL_UI_DELAY;
        let start = Instant::now();

        // Dropping the interval cancels it.
        let mut interval = tokio::time::interval(Duration::from_millis(DELAY_MS * 5));

        loop {
            interval.tick().await;
            let elapsed = start.elapsed();
            if elapsed >= duration {
                break;
            }
            let _ = writeln!(shared_writer, "⏳foo");
        }
    }));

    // Stop spinner. Automatically resumes the terminal.
    if let Some(spinner) = maybe_spinner.as_mut() {
        spinner
            .stop("This is a sample final message for the spinner component: Connected to server")
            .await?;
    }

    tokio::time::sleep(Duration::from_millis(500)).await;

    Ok(())
}

examples/terminal_async.rs (line 425)

    pub fn spawn_task_that_shows_spinner(
        shared_writer: &mut SharedWriter,
        readline: &mut Readline,
        task_name: &str,
        delay: Duration,
    ) {
        let mut interval = interval(delay);
        let mut tick_counter = 0;
        let max_tick_count = 30;

        let task_name = task_name.to_string();

        let shared_writer_clone_1 = shared_writer.clone();
        let mut shared_writer_clone_2 = shared_writer.clone();

        if readline.safe_spinner_is_active.lock().unwrap().is_some() {
            _ = writeln!(
                shared_writer,
                "Spinner is already active, can't start another one"
            );
        }

        tokio::spawn(async move {
            // Try to create and start a spinner.
            let maybe_spinner = Spinner::try_start(
                format!(
                    "{} - This is a sample indeterminate progress message",
                    task_name
                ),
                Duration::from_millis(100),
                SpinnerStyle::default(),
                Arc::new(StdMutex::new(stderr())),
                shared_writer_clone_1,
            )
            .await;

            loop {
                // Check for spinner shutdown (via interruption).
                if let Ok(Some(ref spinner)) = maybe_spinner {
                    if spinner.is_shutdown() {
                        break;
                    }
                }

                // Wait for the interval duration (one tick).
                interval.tick().await;

                // Don't print more than `max_tick_count` times.
                tick_counter += 1;
                if tick_counter >= max_tick_count {
                    break;
                }

                // Display a message at every tick.
                let _ = writeln!(
                    shared_writer_clone_2,
                    "[{task_name}] - [{tick_counter}] interval went off while spinner was spinning!"
                );
            }

            // Don't forget to stop the spinner.
            if let Ok(Some(mut spinner)) = maybe_spinner {
                let msg = format!("{} - Task ended. Resuming terminal and showing any output that was generated while spinner was active.", task_name);
                let _ = spinner.stop(msg.as_str()).await;
            }
        });
    }