Expand description
Run computations in parallel, or not based the parallel
feature toggle.
§in_parallel
(…)
The in_parallel(…)
is the typical fan-out-fan-in mode of parallelism, with thread local storage
made available to a consume(…)
function to process input. The result is sent to the Reduce
running in the calling
thread to aggregate the results into a single output, which is returned by in_parallel()
.
Interruptions can be achieved by letting the reducers feed(…)
method fail.
It gets a boost in usability as it allows threads to borrow variables from the stack, most commonly the repository itself or the data to work on.
This mode of operation doesn’t lend itself perfectly to being wrapped for async
as it appears like a single long-running
operation which runs as fast as possible, which is cancellable only by merit of stopping the input or stopping the output
aggregation.
§reduce::Stepwise
The Stepwise
iterator works exactly as in_parallel()
except that the processing of the output produced by
consume(I, &mut State) -> O
is made accessible by the Iterator
trait’s next()
method. As produced work is not
buffered, the owner of the iterator controls the progress made.
Getting the final output of the Reduce
is achieved through the consuming Stepwise::finalize()
method, which
is functionally equivalent to calling in_parallel()
.
In an async
context this means that progress is only made each time next()
is called on the iterator, while merely dropping
the iterator will wind down the computation without any result.
§Maintaining Safety
In order to assure that threads don’t outlive the data they borrow because their handles are leaked, we enforce
the 'static
lifetime for its inputs, making it less intuitive to use. It is, however, possible to produce
suitable input iterators as long as they can hold something on the heap.
Re-exports§
pub use reduce::Reduce;
Modules§
Structs§
- Evaluate any iterator in their own thread.
- An iterator which olds iterated items with a sequential ID starting at 0 long enough to dispense them in order.
Enums§
- An conditional
EagerIter
, which may become a just-in-time iterator running in the main thread depending on a condition.
Functions§
- build_
thread parallel
Create a builder for threads which allows them to be spawned into a scope and configured prior to spawning. - in_
parallel parallel
Read items frominput
andconsume
them in multiple threads, whose output output is collected by areducer
. Its task is to aggregate these outputs into the final result returned by this function with the benefit of not having to be thread-safe. - in_
parallel_ if parallel
Runin_parallel()
only if the givencondition()
returns true when eagerly evaluated. - in_
parallel_ with_ finalize parallel
Read items frominput
andconsume
them in multiple threads, whose output output is collected by areducer
. Its task is to aggregate these outputs into the final result returned by this function with the benefit of not having to be thread-safe. Caallfinalize
to finish the computation, once per thread, if there was no error sending results earlier. - in_
parallel_ with_ slice parallel
An experiment to have fine-grained per-item parallelization with built-in aggregation via thread state. This is only good for operations where near-random access isn’t detrimental, so it’s not usually great for file-io as it won’t make use of sorted inputs well. Note thatperiodic
is not guaranteed to be called in case other threads come up first and finish too fast.consume(&mut item, &mut stat, &Scope, &threads_available, &should_interrupt)
is called for performing the actual computation. Note thatthreads_available
should be decremented to start a thread that can steal your own work (as stored initem
), which allows callees to implement their own work-stealing in case the work is distributed unevenly. Work stealing should only start after having processed at least one item to give all threads naturally operating on the slice some time to start. Starting threads while slice-workers are still starting up would lead to over-allocation of threads, which is why the number of threads left may turn negative. Once threads are started and stopped, be sure to adjust the thread-count accordingly. - join
parallel
Runsleft
andright
in parallel, returning their output when both are done. - num_
threads parallel
Returns the amount of threads the system can effectively use as the amount of its logical cores. - Return the ‘optimal’ (
size of chunks
,amount of threads as Option
,amount of threads
) to use inin_parallel()
for the givendesired_chunk_size
,num_items
,thread_limit
andavailable_threads
. - threads
parallel
Runsf
with a scope to be used for spawning threads that will not outlive the function call. That way it’s possible to handle threads without needing the ’static lifetime for data they interact with.
Type Aliases§
- Scope
parallel
A scope to start threads within. - A counter for items that are in sequence, to be able to put them back into original order later.