Crate blackhole

Source
Expand description

§Black Hole

…to throw your threads into.

§Project

§Features

Simple thread manager.

§Design

It uses a channel and one job manager thread:

  • When you throw a new job, it checks for active job count.

    • If that count is smaller than limit, it spawns a new runner thread to run that job.

    • If that count is equal to limit:

      • If job queue is smaller than limit, it pushes the job into the queue.
      • Otherwise the job is discarded. An error message is printed to stderr. And the job is returned to you for recovery.

  • When the runner thread finishes the first job, it contacts job manager to ask for new jobs to run. If there are no new jobs, it finishes itself and notifies job manager about that.

  • When job manager receives job-finished-message, it checks job queue to spawn new runner threads, if necessary.

§Examples

use blackhole::{ActiveLimit, BlackHole, Job};

/// # This job takes a `usize`, if it's odd, sends it to Printer
struct Handler {
    data: usize,
}

impl Job for Handler {

    fn run(&mut self) -> Option<Box<dyn Job>> {
        match self.data % 2 {
            0 => None,
            _ => Some(Box::new(Printer { data: self.data })),
        }
    }

}

/// # This job prints data and does nothing else
struct Printer {
    data: usize,
}

impl Job for Printer {

    fn run(&mut self) -> Option<Box<dyn Job>> {
        println!("{}", self.data);
        None
    }

}

let active_limit: ActiveLimit = 4;
let queue_limit: usize = 10;
let black_hole = BlackHole::make_with_active_limit(active_limit, queue_limit).unwrap();
for i in 0 .. queue_limit * 2 {
    match black_hole.throw(Handler { data: i }) {
        Ok(None) => println!("Job is accepted"),
        // If job is discarded, it will be sent back here.
        Ok(Some(job)) => {
            eprintln!("Job is discarded! We'll run it ourselves!");
            blackhole::run_to_end(job);
        },
        Err(err) => {
            eprintln!("BlackHole... exploded: {}", err);
            break;
        },
    };
}
black_hole.escape_on_idle().unwrap();

Modules§

version_info
0.20.2 (January 24th, 2023)

Structs§

BlackHole
Black Hole
OneTime
A job that runs once

Constants§

CODE_NAME
Crate code name
ID
ID of this crate
NAME
Crate name
RELEASE_DATE
Crate release date (year/month/day)
TAG
Tag, which can be used for logging…
VERSION
Crate version

Traits§

Job
A job to be used by BlackHole

Functions§

available_parallelism
Wrapper for std:thread::available_parallelism()
run_to_end
Runs a job to the end

Type Aliases§

ActiveLimit
Active limit
Result
Result type used in this crate