Struct tokio::runtime::Builder[][src]

pub struct Builder { /* fields omitted */ }

Builds Tokio Runtime with custom configuration values.

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

New instances of Builder are obtained via Builder::new_multi_thread or Builder::new_current_thread.

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

Examples

use tokio::runtime::Builder;

fn main() {
    // build runtime
    let runtime = Builder::new_multi_thread()
        .worker_threads(4)
        .thread_name("my-custom-name")
        .thread_stack_size(3 * 1024 * 1024)
        .build()
        .unwrap();

    // use runtime ...
}

Implementations

impl Builder[src]

pub fn new_current_thread() -> Builder[src]

Returns a new builder with the current thread scheduler selected.

Configuration methods can be chained on the return value.

pub fn new_multi_thread() -> Builder[src]

Returns a new builder with the multi thread scheduler selected.

Configuration methods can be chained on the return value.

pub fn enable_all(&mut self) -> &mut Self

Notable traits for &'_ mut F

impl<'_, F> Future for &'_ mut F where
    F: Future + Unpin + ?Sized
type Output = <F as Future>::Output;
[src]

Enables both I/O and time drivers.

Doing this is a shorthand for calling enable_io and enable_time individually. If additional components are added to Tokio in the future, enable_all will include these future components.

Examples

use tokio::runtime;

let rt = runtime::Builder::new_multi_thread()
    .enable_all()
    .build()
    .unwrap();

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

Notable traits for &'_ mut F

impl<'_, F> Future for &'_ mut F where
    F: Future + Unpin + ?Sized
type Output = <F as Future>::Output;
[src]

Sets the number of worker threads the Runtime will use.

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

Default

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

Panic

When using the current_thread runtime this method will panic, since those variants do not allow setting worker thread counts.

Examples

Multi threaded runtime with 4 threads

use tokio::runtime;

// This will spawn a work-stealing runtime with 4 worker threads.
let rt = runtime::Builder::new_multi_thread()
    .worker_threads(4)
    .build()
    .unwrap();

rt.spawn(async move {});

Current thread runtime (will only run on the current thread via Runtime::block_on)

use tokio::runtime;

// Create a runtime that _must_ be driven from a call
// to `Runtime::block_on`.
let rt = runtime::Builder::new_current_thread()
    .build()
    .unwrap();

// This will run the runtime and future on the current thread
rt.block_on(async move {});

Panic

This will panic if val is not larger than 0.

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

Notable traits for &'_ mut F

impl<'_, F> Future for &'_ mut F where
    F: Future + Unpin + ?Sized
type Output = <F as Future>::Output;
[src]

Specifies limit for threads, spawned by the Runtime.

This is number of threads to be used by Runtime, including core_threads Having max_threads less than worker_threads results in invalid configuration when building multi-threaded Runtime, which would cause a panic.

Similarly to the worker_threads, this number should be between 0 and 32,768.

The default value is 512.

When multi-threaded runtime is not used, will act as limit on additional threads.

Otherwise as core_threads are always active, it limits additional threads (e.g. for blocking annotations) as max_threads - core_threads.

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

Notable traits for &'_ mut F

impl<'_, F> Future for &'_ mut F where
    F: Future + Unpin + ?Sized
type Output = <F as Future>::Output;
[src]

Sets name of threads spawned by the Runtime’s thread pool.

The default name is “tokio-runtime-worker”.

Examples


let rt = runtime::Builder::new_multi_thread()
    .thread_name("my-pool")
    .build();

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

Notable traits for &'_ mut F

impl<'_, F> Future for &'_ mut F where
    F: Future + Unpin + ?Sized
type Output = <F as Future>::Output;
where
    F: Fn() -> String + Send + Sync + 'static, 
[src]

Sets a function used to generate the name of threads spawned by the Runtime’s thread pool.

The default name fn is || "tokio-runtime-worker".into().

Examples


let rt = runtime::Builder::new_multi_thread()
    .thread_name_fn(|| {
       static ATOMIC_ID: AtomicUsize = AtomicUsize::new(0);
       let id = ATOMIC_ID.fetch_add(1, Ordering::SeqCst);
       format!("my-pool-{}", id)
    })
    .build();

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

Notable traits for &'_ mut F

impl<'_, F> Future for &'_ mut F where
    F: Future + Unpin + ?Sized
type Output = <F as Future>::Output;
[src]

Sets 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 rt = runtime::Builder::new_multi_thread()
    .thread_stack_size(32 * 1024)
    .build();

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

Notable traits for &'_ mut F

impl<'_, F> Future for &'_ mut F where
    F: Future + Unpin + ?Sized
type Output = <F as Future>::Output;
where
    F: Fn() + Send + Sync + 'static, 
[src]

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

This is intended for bookkeeping and monitoring use cases.

Examples


let runtime = runtime::Builder::new_multi_thread()
    .on_thread_start(|| {
        println!("thread started");
    })
    .build();

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

Notable traits for &'_ mut F

impl<'_, F> Future for &'_ mut F where
    F: Future + Unpin + ?Sized
type Output = <F as Future>::Output;
where
    F: Fn() + Send + Sync + 'static, 
[src]

Executes function f before each thread stops.

This is intended for bookkeeping and monitoring use cases.

Examples


let runtime = runtime::Builder::new_multi_thread()
    .on_thread_stop(|| {
        println!("thread stopping");
    })
    .build();

pub fn build(&mut self) -> Result<Runtime>[src]

Creates the configured Runtime.

The returned Runtime instance is ready to spawn tasks.

Examples

use tokio::runtime::Builder;

let rt  = Builder::new_multi_thread().build().unwrap();

rt.block_on(async {
    println!("Hello from the Tokio runtime");
});

pub fn thread_keep_alive(&mut self, duration: Duration) -> &mut Self

Notable traits for &'_ mut F

impl<'_, F> Future for &'_ mut F where
    F: Future + Unpin + ?Sized
type Output = <F as Future>::Output;
[src]

Sets a custom timeout for a thread in the blocking pool.

By default, the timeout for a thread is set to 10 seconds. This can be overriden using .thread_keep_alive().

Example


let rt = runtime::Builder::new_multi_thread()
    .thread_keep_alive(Duration::from_millis(100))
    .build();

impl Builder[src]

pub fn enable_io(&mut self) -> &mut Self

Notable traits for &'_ mut F

impl<'_, F> Future for &'_ mut F where
    F: Future + Unpin + ?Sized
type Output = <F as Future>::Output;
[src]

Enables the I/O driver.

Doing this enables using net, process, signal, and some I/O types on the runtime.

Examples

use tokio::runtime;

let rt = runtime::Builder::new_multi_thread()
    .enable_io()
    .build()
    .unwrap();

impl Builder[src]

pub fn enable_time(&mut self) -> &mut Self

Notable traits for &'_ mut F

impl<'_, F> Future for &'_ mut F where
    F: Future + Unpin + ?Sized
type Output = <F as Future>::Output;
[src]

Enables the time driver.

Doing this enables using tokio::time on the runtime.

Examples

use tokio::runtime;

let rt = runtime::Builder::new_multi_thread()
    .enable_time()
    .build()
    .unwrap();

Trait Implementations

impl Debug for Builder[src]

Auto Trait Implementations

impl !RefUnwindSafe for Builder

impl Send for Builder

impl Sync for Builder

impl Unpin for Builder

impl !UnwindSafe for Builder

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.