Struct tokio_threadpool::Builder

pub struct Builder { /* fields omitted */ }

Builds a thread pool with custom configuration values.

Methods can be chanined 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;

// Create a thread pool with default configuration values
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();

Methods

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;

// Create a thread pool with default configuration values
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

// Create a thread pool with default configuration values
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

// Create a thread pool with default configuration values
let thread_pool = Builder::new()
    .max_blocking(200)
    .build();

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

Set the worker thread keep alive duration

If set, a worker thread will wait for up to the specified duration for work, at which point the thread will shutdown. When work becomes available, a new thread will eventually be spawned to replace the one that shut down.

When the value is None, the thread will wait for work forever.

The default value is None.

Examples

use std::time::Duration;

// Create a thread pool with default configuration values
let thread_pool = Builder::new()
    .keep_alive(Some(Duration::from_secs(30)))
    .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

// Create a thread pool with default configuration values
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

// Create a thread pool with default configuration values
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

// Create a thread pool with default configuration values
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

// Create a thread pool with default configuration values
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

// Create a thread pool with default configuration values
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

// Create a thread pool with default configuration values
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 therad 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

// Create a thread pool with default configuration values
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.