Struct r3bl_terminal_async::public_api::spinner::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<bool>,
}

Fields

tick_delay: Duration

message: String

style: SpinnerStyle

safe_output_terminal: SafeRawTerminal

shared_writer: SharedWriter

shutdown_sender: Sender<bool>

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

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

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

        let line_sender = shared_writer.line_sender.clone();
        let task_name = task_name.to_string();

        let shared_writer_clone = shared_writer.clone();

        tokio::spawn(async move {
            // Create 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,
            )
            .await;

            loop {
                // 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 msg = format!("[{task_name}] - [{tick_counter}] interval went off while spinner was spinning!\n");
                let _ = line_sender
                    .send(LineControlSignal::Line(msg.into_bytes()))
                    .await;
            }

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

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

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

        let line_sender = shared_writer.line_sender.clone();
        let task_name = task_name.to_string();

        let shared_writer_clone = shared_writer.clone();

        tokio::spawn(async move {
            // Create 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,
            )
            .await;

            loop {
                // 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 msg = format!("[{task_name}] - [{tick_counter}] interval went off while spinner was spinning!\n");
                let _ = line_sender
                    .send(LineControlSignal::Line(msg.into_bytes()))
                    .await;
            }

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