Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/dtolnay/oqueue

Non-interleaving multithreaded output queue
https://github.com/dtolnay/oqueue

Last synced: 18 days ago
JSON representation

Non-interleaving multithreaded output queue

Awesome Lists containing this project

README 

        
Non-interleaving output queue

=============================



[github](https://github.com/dtolnay/oqueue)

[crates.io](https://crates.io/crates/oqueue)

[docs.rs](https://docs.rs/oqueue)

[build status](https://github.com/dtolnay/oqueue/actions?query=branch%3Amaster)



Mechanism to prevent interleaving of output of tasks while still allowing an

arbitrary number of tasks to make progress, even ones other than the task

currently printing output.



```toml

[dependencies]

oqueue = "0.1"

```







## Use case



This crate addresses a seemingly narrow use case, but it is one I have hit in a

couple different circumstances.



Suppose we have some embarrassingly parallel workload where each piece of work

may want to write to stdout/stderr. If we just parallelize this naïvely, output

from different tasks will interleave and end up unreadable. If we make each task

lock the output stream, do its work, and then unlock, we avoid interleaving but

tasks can no longer run in parallel. If we have each task write its output into

a local buffer and print it all atomically at the end, all output is

unnecessarily delayed and the application can feel lurchy and unresponsive

because none of the output is seen in real time.







## Objective



  - We have an ordered sequence of tasks 0..N.



  - We want to receive all output from task 0, then all output from task 1, etc

    in order. Task output must not interleave with other tasks and must follow

    the task order.



  - We want tasks to execute in parallel.



  - We want all output to be printed as soon as possible, meaning real time for

    exactly one task at a time and deferred until replacement of the realtime

    task for other tasks.







## Example



This example uses oqueue to sequence the output of worker threads on a Rayon

threadpool.



```rust

use oqueue::{Color::Red, Sequencer, Task};

use rayon::ThreadPoolBuilder;

use std::error::Error;

use std::fs;

use std::path::{Path, PathBuf};

use std::thread;

use std::time::Duration;



type Result = std::result::Result>;



fn main() -> Result<()> {

    // Come up with some work that needs to be performed. Let's pretend to

    // perform work on each file in the current directory.

    let mut files = Vec::new();

    for entry in fs::read_dir(".")? {

        files.push(entry?.path());

    }

    files.sort();



    // Build a thread pool with one thread per cpu.

    let cpus = num_cpus::get();

    let pool = ThreadPoolBuilder::new().num_threads(cpus).build()?;



    // Spin up the right number of worker threads. They will write to stderr.

    let oqueue = Sequencer::stderr();

    pool.scope(|scope| {

        for _ in 0..cpus {

            scope.spawn(|_| worker(&oqueue, &files));

        }

    });



    Ok(())

}



fn worker(oqueue: &Sequencer, inputs: &[PathBuf]) {

    // Perform tasks indicated by the sequencer.

    loop {

        let task = oqueue.begin();

        match inputs.get(task.index) {

            Some(path) => work(task, path),

            None => return,

        }

    }

}



fn work(task: Task, path: &Path) {

    // Produce output by writing to the task.

    write!(task, "evaluating ");

    task.bold();

    writeln!(task, "{}", path.display());



    // Do some expensive work...

    let string = path.to_string_lossy();

    thread::sleep(Duration::from_millis(150 * string.len() as u64));



    // ... which may fail or succeed.

    if string.contains('c') {

        task.bold_color(Red);

        write!(task, "  ERROR");

        task.reset_color();

        writeln!(task, ": path contains the letter 'c'");

    }

}

```



The output of this program is guaranteed to display tasks in the intended

sorted order and non-interleaved. Tasks will make progress in parallel

without needing to wait to perform output. All output will appear the

earliest possible including one task in real time at all times.




evaluating ./.git

evaluating ./.gitignore

evaluating ./Cargo.lock

  ERROR: path contains the letter 'c'

evaluating ./Cargo.toml

evaluating ./LICENSE-APACHE

evaluating ./LICENSE-MIT

evaluating ./README.md

evaluating ./examples

evaluating ./src

  ERROR: path contains the letter 'c'

evaluating ./target








## Further reading



  - The [`oqueue::Sequencer`][Sequencer] documentation covers some different

    techniques for distributing work items across tasks.



  - The [`oqueue::Task`][Task] documentation shows the APIs for setting

    output color and writing output to a task.



[Sequencer]: https://docs.rs/oqueue/0.1/oqueue/struct.Sequencer.html

[Task]: https://docs.rs/oqueue/0.1/oqueue/struct.Task.html







#### License





Licensed under either of Apache License, Version

2.0 or MIT license at your option.










Unless you explicitly state otherwise, any contribution intentionally submitted

for inclusion in this crate by you, as defined in the Apache-2.0 license, shall

be dual licensed as above, without any additional terms or conditions.