Struct Builder

pub struct Builder { /* private fields */ }

Builds a thread pool with custom configuration values.

Methods can be chained in order to set the configuration values. The thread pool is constructed by calling build.

New instances of Builder are obtained via Builder::new.

See function level documentation for details on the various configuration settings.

Examples

use futures::future::{Future, lazy};
use std::time::Duration;

let thread_pool = Builder::new()
    .pool_size(4)
    .keep_alive(Some(Duration::from_secs(30)))
    .build();

thread_pool.spawn(lazy(|| {
    println!("called from a worker thread");
    Ok(())
}));

// Gracefully shutdown the threadpool
thread_pool.shutdown().wait().unwrap();

Implementations

impl Builder

pub fn new() -> Builder

Returns a new thread pool builder initialized with default configuration values.

Configuration methods can be chained on the return value.

Examples

use std::time::Duration;

let thread_pool = Builder::new()
    .pool_size(4)
    .keep_alive(Some(Duration::from_secs(30)))
    .build();

pub fn pool_size(&mut self, val: usize) -> &mut Self

Set the maximum number of worker threads for the thread pool instance.

This must be a number between 1 and 32,768 though it is advised to keep this value on the smaller side.

The default value is the number of cores available to the system.

Examples

let thread_pool = Builder::new()
    .pool_size(4)
    .build();

pub fn max_blocking(&mut self, val: usize) -> &mut Self

Set the maximum number of concurrent blocking sections.

When the maximum concurrent blocking calls is reached, any further calls to blocking will return NotReady and the task is notified once previously in-flight calls to blocking return.

This must be a number between 1 and 32,768 though it is advised to keep this value on the smaller side.

The default value is 100.

Examples

let thread_pool = Builder::new()
    .max_blocking(200)
    .build();

pub fn keep_alive(&mut self, val: Option<Duration>) -> &mut Self

Set the thread keep alive duration

If set, a thread that has completed a blocking call will wait for up to the specified duration to become a worker thread again. Once the duration elapses, the thread will shutdown.

When the value is None, the thread will wait to become a worker thread forever.

The default value is None.

Examples

use std::time::Duration;

let thread_pool = Builder::new()
    .keep_alive(Some(Duration::from_secs(30)))
    .build();

pub fn panic_handler<F>(&mut self, f: F) -> &mut Self

where F: Fn(Box<dyn Any + Send>) + Send + Sync + 'static,

Sets a callback to be triggered when a panic during a future bubbles up to Tokio. By default Tokio catches these panics, and they will be ignored. The parameter passed to this callback is the same error value returned from std::panic::catch_unwind(). To abort the process on panics, use std::panic::resume_unwind() in this callback as shown below.

Examples

let thread_pool = Builder::new()
    .panic_handler(|err| std::panic::resume_unwind(err))
    .build();

pub fn name_prefix<S: Into<String>>(&mut self, val: S) -> &mut Self

Set name prefix of threads spawned by the scheduler

Thread name prefix is used for generating thread names. For example, if prefix is my-pool-, then threads in the pool will get names like my-pool-1 etc.

If this configuration is not set, then the thread will use the system default naming scheme.

Examples

let thread_pool = Builder::new()
    .name_prefix("my-pool-")
    .build();

pub fn stack_size(&mut self, val: usize) -> &mut Self

Set the stack size (in bytes) for worker threads.

The actual stack size may be greater than this value if the platform specifies minimal stack size.

The default stack size for spawned threads is 2 MiB, though this particular stack size is subject to change in the future.

Examples

let thread_pool = Builder::new()
    .stack_size(32 * 1024)
    .build();

pub fn around_worker<F>(&mut self, f: F) -> &mut Self

where F: Fn(&Worker, &mut Enter) + Send + Sync + 'static,

Execute function f on each worker thread.

This function is provided a handle to the worker and is expected to call Worker::run, otherwise the worker thread will shutdown without doing any work.

Examples

let thread_pool = Builder::new()
    .around_worker(|worker, _| {
        println!("worker is starting up");
        worker.run();
        println!("worker is shutting down");
    })
    .build();

pub fn after_start<F>(&mut self, f: F) -> &mut Self

where F: Fn() + Send + Sync + 'static,

Execute function f after each thread is started but before it starts doing work.

This is intended for bookkeeping and monitoring use cases.

Examples

let thread_pool = Builder::new()
    .after_start(|| {
        println!("thread started");
    })
    .build();

pub fn before_stop<F>(&mut self, f: F) -> &mut Self

where F: Fn() + Send + Sync + 'static,

Execute function f before each thread stops.

This is intended for bookkeeping and monitoring use cases.

Examples

let thread_pool = Builder::new()
    .before_stop(|| {
        println!("thread stopping");
    })
    .build();

pub fn custom_park<F, P>(&mut self, f: F) -> &mut Self

where F: Fn(&WorkerId) -> P + 'static, P: Park + Send + 'static, P::Error: Error,

Customize the park instance used by each worker thread.

The provided closure f is called once per worker and returns a Park instance that is used by the worker to put itself to sleep.

Examples

let thread_pool = Builder::new()
    .custom_park(|_| {
        use tokio_threadpool::park::DefaultPark;

        // This is the default park type that the worker would use if we
        // did not customize it.
        let park = DefaultPark::new();

        // Decorate the `park` instance, allowing us to customize work
        // that happens when a worker thread goes to sleep.
        decorate(park)
    })
    .build();

pub fn build(&self) -> ThreadPool

Create the configured ThreadPool.

The returned ThreadPool instance is ready to spawn tasks.

Examples

let thread_pool = Builder::new()
    .build();

Trait Implementations

impl Debug for Builder

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.