Struct OrderedThreadpool

pub struct OrderedThreadpool<'scope, 'env, I, O> { /* private fields */ }

An ordered thread pool.

Yields results in the same order they are submitted to the pool.

Retains much of the same functionality as a normal Threadpool; refer to the documentation there for more general information about the thread pools. It maintains many of the same implementation details and limitations as well, so if not stated otherwise, assume the two pools work in the same way.

Also like the Threadpool, the OrderedThreadpool has its own OrderedThreadpoolBuilder, which allows you to configure all the same options as you would be able to with a ThreadpoolBuilder.

One implementation difference between this pool and the standard unordered Threadpool is that when passing a worker function to OrderedThreadpoolBuilder::build, alongside a thread id, the function also receives a monotonically increasing “job index” usize value. This value does not necessarily represent the original index of its corresponding input. It is simply a monotonically increasing value unique among all inputs given to this threadpool. In the event that this threadpool is used to only process a single iterator, the job index will represent that index. However, subsequent iterators submitted to the pool will not maintain that property; a new pool will have to be constructed if that is desired.

As this pool is guaranteed to preserve ordering of its inputs, it can be used to perform multithreaded map and filter operations on iterators passed to it. As such, it has an additional method OrderedThreadpool::filter_map. This works as you would expect, similar to its Iterator counterpart, Iterator::filter_map. Some iterator extensions FilterMapMultithread::filter_map_multithread and FilterMapAsync::filter_map_async are available to make this usage pattern even more seamless.

Of note, in exchange for yielding ordered outputs, results are no longer guaranteed to return immediately once they finish processing; there may be some delay, as results returned sooner than intended are placed inside a buffer, which also uses some additional amount of memory.

Implementations

impl<'scope, 'env, I, O> OrderedThreadpool<'scope, 'env, I, O>

pub fn new<F>(f: F, scope: &'scope Scope<'scope, 'env>) -> Self

where F: Fn(I) -> Option<O> + Send + Sync + 'scope, I: Send + Sync + 'scope, O: Send + Sync + 'scope,

Construct a new OrderedThreadpool.

Provide a function that workers will use to process jobs, and a Scope that the pool will use to spawn worker threads and any producer / consumer threads.

By default, the number of workers spawned is determined by the result of available_parallelism. To specify the specific number of workers to spawn, and configure several additional other custom properties including an initializer and thread blocking properties, construct your pool via an OrderedThreadpoolBuilder instead.

pub fn filter_map<'a, T>( &'a self, iter: T, ) -> OrderedThreadpoolIter<'a, 'scope, 'env, I, O>

where I: Send + Sync + 'scope, O: Send + Sync + 'scope, T: IntoIterator<Item = I>,

Use this pool to perform a multithreaded filter_map on the passed iterator.

Equivalent to calling OrderedThreadpool::submit_all, followed by OrderedThreadpool::iter.

pub fn filter_map_async<'a, T>( &'a self, iter: T, ) -> OrderedThreadpoolIter<'a, 'scope, 'env, I, O>

where I: Send + Sync + 'scope, O: Send + Sync + 'scope, T: IntoIterator<Item = I> + Send + Sync + 'scope,

Use this pool to perform a multithreaded filter_map on the passed iterator.

Passes the iterator up to a producer thread, so that results can be consumed from the pool immediately, even before the iterator finishes being exhausted.

Trait Implementations

impl<'scope, 'env, I, O> Extend<I> for OrderedThreadpool<'scope, 'env, I, O>

where I: Send + Sync + 'scope, O: Send + Sync + 'scope,

fn extend<T: IntoIterator<Item = I>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<'scope, 'env, I, O> GenericThreadpool<'scope, I, O> for OrderedThreadpool<'scope, 'env, I, O>

where I: Send + Sync + 'scope, O: Send + Sync + 'scope,

fn producer<T>(&self, iter: T) -> ScopedJoinHandle<'scope, ()>

where I: Send + Sync + 'scope, T: IntoIterator<Item = I> + Send + Sync + 'scope,

Spawn a new producer thread, which supplies jobs to the pool from the passed iterator asynchronously on a separate thread.

Because of the ordered nature of this pool, you probably don’t want to be submitting multiple jobs to the pool simultaneously from separate threads, as the results will become intermixed nondeterministically with each other. Nonetheless, even in such circumstances, the pool guarantees that the original ordering of the individual iterators will still be preserved, even if the specific interspersing of their individual elements is undefined and nondeterministic.

type Iter<'a> = OrderedThreadpoolIter<'a, 'scope, 'env, I, O> where Self: 'a

type JoinHandle = ScopedJoinHandle<'scope, ()>

fn submit(&self, input: I)

Synchronously submit a single job to the pool.

fn recv(&self) -> O

Block the current thread until a result from the pool is available, and return it.

fn try_recv(&self) -> Option<O>

Check if a result is available from the pool; if so, return it. If not, returns None.

fn iter(&self) -> OrderedThreadpoolIter<'_, 'scope, 'env, I, O>

Iterate over the currently available results in the pool.

fn wait_until_finished(&self)

Block until all producers have been exhausted, and all workers have finished processing all jobs.

fn consumer<F>(&self, f: F) -> ScopedJoinHandle<'scope, ()>

where O: Send + Sync + 'scope, F: Fn(O) + Sync + Send + 'scope,

Spawn a new consumer thread, which consumes and processes results from the workers asynchronously on a separate thread.

fn submit_all<T>(&self, iter: T)

where T: IntoIterator<Item = I>,

Synchronously submit many jobs to the pool at once from an iterator or collection.

impl<'scope, 'env, I, O> IntoIterator for OrderedThreadpool<'scope, 'env, I, O>

type Item = O

The type of the elements being iterated over.

type IntoIter = IntoIter<O>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.