Struct jobpool::JobPool

pub struct JobPool { /* fields omitted */ }

JobPool manages a job queue to be run on a specified number of threads.

Methods

impl JobPool

pub fn new(size: usize) -> Self

Creates a new job pool.

Using the number of cpu cores as the argument for size is recommended. Higher values can result iSeqCstn larger memory footprint, and non-optimal performance.

Panics

This function will panic if the argument for size is 0.

Examples

use jobpool::JobPool;

let pool_size: usize = 8; // number of cpu cores is recommended
let mut pool = JobPool::new(pool_size);
pool.queue(|| {
    // do some work
});
// ...
pool.shutdown(); // blocks until all jobs are done

pub fn queue<J>(&mut self, job: J) where
    J: Runnable + Send + 'static, 

Queues a new job.

A job can be a closure with no arguments and returns, or a type with Runnable trait. A queued job gets run in a first-come, first-serve basis.

Panics

This method will panic if the JobPool instance has already been shutdown.

Examples

use jobpool::JobPool;

let pool_size: usize = 8; // number of cpu cores is recommended
let mut pool = JobPool::new(pool_size);
pool.queue(|| {
    // do some work
});
// ...
pool.shutdown(); // blocks until all jobs are done

pub fn queue_with_priority<J>(&mut self, job: J, priority: isize) where
    J: Runnable + Send + 'static, 

Queues a new job with a given priority.

A job can be a closure with no arguments and returns, or a type with Runnable trait. A queued job with highest priority runs at given time. The value for priority is totally relative. The constant NORMAL_PRIORITY (value = 0) can be used as reference.

Panics

This method will panic if the JobPool instance has already been shutdown.

Examples

use jobpool::JobPool;

let pool_size: usize = 8; // number of cpu cores is recommended
let mut pool = JobPool::new(pool_size);

for i in -10..10 {
    pool.queue_with_priority(move || {
        // do some work
    }, jobpool::NORMAL_PRIORITY + i);
}
// ...
pool.shutdown(); // blocks until all jobs are done

pub fn auto_grow(&mut self, max_size: usize)

Automatically increase the number of worker threads as needed until max_size is reached.

Panics

This method will panic if max_size is less than or equal to initial JobPool size.

Examples

use jobpool::JobPool;

let pool_size: usize = 8; // number of cpu cores is recommended
let mut pool = JobPool::new(pool_size);
pool.auto_grow(100);
for _ in 0..1000 {
    pool.queue(|| {
        // do some work
    });
}
// ...
pool.shutdown(); // blocks until all jobs are done

pub fn active_workers_count(&self) -> usize

Get the number of current active worker threads.

pub fn shutdown(&mut self)

Shuts down this instance of JobPool.

This method will wait for all of the queued jobs to finish. It also gets called automatically as the instance goes out of scope, so calling this method can be optional.

Examples

use jobpool::JobPool;

let pool_size: usize = 8; // number of cpu cores is recommended
let mut pool = JobPool::new(pool_size);
pool.queue(|| {
    // do some work
});
// ...
pool.shutdown(); // blocks until all jobs are done

pub fn shutdown_no_wait(&mut self) -> Option<Vec<JoinHandle<()>>>

Shuts down this instance of JobPool without waiting for threads to finish.

This method will return all of the threads' JoinHandles (as few as initial JobPool size, and as many as additional active threads if auto_grow(...) has been used. It won't wait for the threads to finish, and it must be called explicitly. Once this method is called, this instance of JobPool will throw away jobs already in the queue while running the one at hand. Calling shutdown() after this method won't have any effect. Unlike shutdown(), it doesn't get called automatically after going out of scope.

Examples

use jobpool::JobPool;

let pool_size: usize = 8; // number of cpu cores is recommended
let mut pool = JobPool::new(pool_size);
pool.queue(|| {
    // do some work
});
// ...
let handles = pool.shutdown_no_wait();
// ...
if let Some(handles) = handles {
    for handle in handles {
        let _ = handle.join();
    }
}

pub fn has_shutdown(&self) -> bool

Check whether this JobPool instance has been shutdown.

Trait Implementations

impl Drop for JobPool

fn drop(&mut self)

Executes the destructor for this type.