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

    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: Unpin + Future + ?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: Unpin + Future + ?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_blocking_threads(&mut self, val: usize) -> &mut Selfⓘ

### Notable traits for &'_ mut F

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

Specifies limit for threads spawned by the Runtime used for blocking operations.

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

The default value is 512.

Otherwise as `worker_threads` are always active, it limits additional threads (e.g. for blocking annotations).

# Panic

This will panic if `val` is not larger than `0`.

#### `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: Unpin + Future + ?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: Unpin + Future + ?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: Unpin + Future + ?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: Unpin + Future + ?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: Unpin + Future + ?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: Unpin + Future + ?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: Unpin + Future + ?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: Unpin + Future + ?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]

#### `fn fmt(&self, fmt: &mut Formatter<'_>) -> Result` [src]

Formats the value using the given formatter. Read more

## 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]

#### `pub fn type_id(&self) -> TypeId` [src]

Gets the `TypeId` of `self`. Read more

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

#### `pub fn borrow(&self) -> &Tⓘ

### Notable traits for &'_ mut F

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

Immutably borrows from an owned value. Read more

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

#### `pub fn borrow_mut(&mut self) -> &mut Tⓘ

### Notable traits for &'_ mut F

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

Mutably borrows from an owned value. Read more

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

#### `pub fn from(t: T) -> T` [src]

Performs the conversion.

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

#### `pub fn into(self) -> U` [src]

Performs the conversion.

### `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.

#### `pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>` [src]

Performs the conversion.

### `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.

#### `pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>` [src]

Performs the conversion.