Struct iroh_blobs::util::local_pool::LocalPool

pub struct LocalPool { /* private fields */ }

A local task pool with proper shutdown

Unlike LocalPoolHandle, this pool will join all its threads when dropped, ensuring that all Drop implementations are run to completion.

On drop, this pool will immediately cancel all tasks that are currently being executed, and will wait for all threads to finish executing their loops before returning. This means that all drop implementations will be able to run to completion before drop exits.

On LocalPool::finish, this pool will notify all threads to shut down, and then wait for all threads to finish executing their loops before returning. This means that all currently executing tasks will be allowed to run to completion.

The pool will install the [tracing::Subscriber] which was set on the current thread of where it was created as the default subscriber in all spawned threads.

Implementations

impl LocalPool

pub fn single() -> Self

Create a new local pool with a single std thread.

pub fn new(config: Config) -> Self

Create a new local pool with the given config.

This will use the current tokio runtime handle, so it must be called from within a tokio runtime.

pub fn handle(&self) -> &LocalPoolHandle

Get a cheaply cloneable handle to the pool

This is not strictly necessary since we implement deref for LocalPoolHandle, but makes getting a handle more explicit.

pub async fn cancelled(&self)

A future that resolves when the pool is cancelled

pub async fn shutdown(self)

Immediately stop polling all tasks and wait for all threads to finish.

This is like drop, but waits for thread completion asynchronously.

If there was a panic on any of the threads, it will be re-thrown here.

pub async fn finish(self)

Gently shut down the pool

Notifies all the pool threads to shut down and waits for them to finish.

If you just want to drop the pool without giving the threads a chance to process their remaining tasks, just use Self::shutdown.

If you want to wait for only a limited time for the tasks to finish, you can race this function with a timeout.

Methods from Deref<Target = LocalPoolHandle>

pub fn waiting_tasks(&self) -> usize

Get the number of tasks in the queue

This is not the number of tasks being executed, but the number of tasks waiting to be scheduled for execution. If this number is high, it indicates that the pool is very busy.

You might want to use this to throttle or reject requests.

pub fn try_spawn<T, F, Fut>(&self, gen: F) -> Result<Run<T>, SpawnError>

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

Spawn a task in the pool and return a future that resolves when the task is done.

If you don’t care about the result, prefer LocalPoolHandle::spawn_detached since it is more efficient.

pub fn try_spawn_detached<F, Fut>(&self, gen: F) -> Result<(), SpawnError>

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

Spawn a task in the pool.

The task will run to completion unless the pool is shut down or the task panics. In case of panic, the pool will either log the panic and continue or immediately shut down, depending on the PanicMode.

pub fn spawn<T, F, Fut>(&self, gen: F) -> Run<T>

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

Spawn a task in the pool and await the result.

Like LocalPoolHandle::try_spawn, but panics if the pool is shut down.

pub fn spawn_detached<F, Fut>(&self, gen: F)

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

Spawn a task in the pool.

Like LocalPoolHandle::try_spawn_detached, but panics if the pool is shut down.

pub fn try_spawn_detached_boxed( &self, gen: Box<dyn FnOnce() -> Pin<Box<dyn Future<Output = ()>>> + Send + 'static> ) -> Result<(), SpawnError>

Spawn a task in the pool.

This is like LocalPoolHandle::try_spawn_detached, but assuming that the generator function is already boxed. This is the lowest overhead way to spawn a task in the pool.

Trait Implementations

impl Debug for LocalPool

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

Formats the value using the given formatter.

impl Default for LocalPool

fn default() -> Self

Returns the “default value” for a type.

impl Deref for LocalPool

type Target = LocalPoolHandle

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Drop for LocalPool

fn drop(&mut self)

Executes the destructor for this type.