Struct LocalPoolHandle

pub struct LocalPoolHandle { /* private fields */ }

Available on crate feature rt only.

A cloneable handle to a local pool, used for spawning !Send tasks.

Internally the local pool uses a tokio::task::LocalSet for each worker thread in the pool. Consequently you can also use tokio::task::spawn_local (which will execute on the same thread) inside the Future you supply to the various spawn methods of LocalPoolHandle.

Examples

use std::rc::Rc;
use tokio::task;
use tokio_util::task::LocalPoolHandle;

#[tokio::main(flavor = "current_thread")]
async fn main() {
    let pool = LocalPoolHandle::new(5);

    let output = pool.spawn_pinned(|| {
        // `data` is !Send + !Sync
        let data = Rc::new("local data");
        let data_clone = data.clone();

        async move {
            task::spawn_local(async move {
                println!("{}", data_clone);
            });
     
            data.to_string()
        }   
    }).await.unwrap();
    println!("output: {}", output);
}

Implementations

impl LocalPoolHandle

pub fn new(pool_size: usize) -> LocalPoolHandle

Create a new pool of threads to handle !Send tasks. Spawn tasks onto this pool via LocalPoolHandle::spawn_pinned.

Panics

Panics if the pool size is less than one.

pub fn num_threads(&self) -> usize

Returns the number of threads of the Pool.

pub fn get_task_loads_for_each_worker(&self) -> Vec<usize>

Returns the number of tasks scheduled on each worker. The indices of the worker threads correspond to the indices of the returned Vec.

pub fn spawn_pinned<F, Fut>(&self, create_task: F) -> JoinHandle<Fut::Output>

where F: FnOnce() -> Fut + Send + 'static, Fut: Future + 'static, Fut::Output: Send + 'static,

Spawn a task onto a worker thread and pin it there so it can’t be moved off of the thread. Note that the future is not Send, but the FnOnce which creates it is.

Examples

use std::rc::Rc;
use tokio_util::task::LocalPoolHandle;

#[tokio::main]
async fn main() {
    // Create the local pool
    let pool = LocalPoolHandle::new(1);

    // Spawn a !Send future onto the pool and await it
    let output = pool
        .spawn_pinned(|| {
            // Rc is !Send + !Sync
            let local_data = Rc::new("test");

            // This future holds an Rc, so it is !Send
            async move { local_data.to_string() }
        })
        .await
        .unwrap();

    assert_eq!(output, "test");
}

pub fn spawn_pinned_by_idx<F, Fut>( &self, create_task: F, idx: usize, ) -> JoinHandle<Fut::Output>

where F: FnOnce() -> Fut + Send + 'static, Fut: Future + 'static, Fut::Output: Send + 'static,

Differs from spawn_pinned only in that you can choose a specific worker thread of the pool, whereas spawn_pinned chooses the worker with the smallest number of tasks scheduled.

A worker thread is chosen by index. Indices are 0 based and the largest index is given by num_threads() - 1

Panics

This method panics if the index is out of bounds.

Examples

This method can be used to spawn a task on all worker threads of the pool:

use tokio_util::task::LocalPoolHandle;

#[tokio::main]
async fn main() {
    const NUM_WORKERS: usize = 3;
    let pool = LocalPoolHandle::new(NUM_WORKERS);
    let handles = (0..pool.num_threads())
        .map(|worker_idx| {
            pool.spawn_pinned_by_idx(
                || {
                    async {
                        "test"
                    }
                },
                worker_idx,
            )
        })
        .collect::<Vec<_>>();

    for handle in handles {
        handle.await.unwrap();
    }
}

Trait Implementations

impl Clone for LocalPoolHandle

fn clone(&self) -> LocalPoolHandle

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for LocalPoolHandle

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

Formats the value using the given formatter.