Crate blackhole

Black Hole

...to throw your threads into.

Project

• Repository: https://bitbucket.org/haibison/blackhole
• License: Nice License 1.0.0 (see LICENSE file at root directory of master branch)
• This project follows Semantic Versioning 2.0.0

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(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.18.0 (December 13th, 2020)

Macros

get_online_processors

Gets online processors

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

run_to_end

Runs a job to the end

Type Definitions

ActiveLimit	Active limit
Result	Result type used in this crate