Enum NumThreads

pub enum NumThreads {
    Auto,
    Max(NonZero<usize>),
}

NumThreads represents the degree of parallelization. It is possible to define an upper bound on the number of threads to be used for the parallel computation. When set to 1, the computation will be executed sequentially without any overhead. In this sense, parallel iterators defined in this crate are a union of sequential and parallel execution.

Rules of Thumb / Guidelines

It is recommended to set this parameter to its default value, NumThreads::Auto. This setting assumes that it can use all available threads; however, the computation will spawn new threads only when required. In other words, when we can dynamically decide that the task is not large enough to justify spawning a new thread, the parallel execution will avoid it.

A special case is NumThreads::Max(NonZeroUsize::new(1).unwrap()), or equivalently NumThreads::sequential(). This will lead to a sequential execution of the defined computation on the main thread. Both in terms of used resources and computation time, this mode is not similar but identical to a sequential execution using the regular sequential Iterators.

Lastly, NumThreads::Max(t) where t >= 2 can be used in the following scenarios:

• We have a strict limit on the resources that we can use for this computation, even if the hardware has more resources. Parallel execution will ensure that t will never be exceeded.
• We have a computation which is extremely time-critical and our benchmarks show that t outperforms the NumThreads::Auto on the corresponding system.

Variants

Auto

This setting assumes that it can use all available threads; however, the computation will spawn new threads only when required. In other words, when we can dynamically decide that the task is not large enough to justify spawning a new thread, the parallel execution will avoid it.

Max(NonZero<usize>)

Limits the maximum number of threads that can be used by the parallel execution.

A special case is NumThreads::Max(NonZeroUsize::new(1).unwrap()), or equivalently NumThreads::sequential(). This will lead to a sequential execution of the defined computation on the main thread. Both in terms of used resources and computation time, this mode is not similar but identical to a sequential execution using the regular sequential Iterators.

Lastly, NumThreads::Max(t) where t >= 2 can be used in the following scenarios:

• We have a strict limit on the resources that we can use for this computation, even if the hardware has more resources. Parallel execution will ensure that t will never be exceeded.
• We have a computation which is extremely time-critical and our benchmarks show that t outperforms the NumThreads::Auto on the corresponding system.

Implementations

impl NumThreads

pub const fn sequential() -> NumThreads

Equivalent to NumThreads::Max(NonZeroUsize::new(1).unwrap()).

This will lead to a sequential execution of the defined computation on the main thread. Both in terms of used resources and computation time, this mode is not similar but identical to a sequential execution using the regular sequential Iterators.

pub fn is_sequential(self) -> bool

Returns true if number of threads is set to 1.

Note that in this case the computation will be executed sequentially using regular iterators.

Trait Implementations

impl Clone for NumThreads

fn clone(&self) -> NumThreads

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for NumThreads

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

Formats the value using the given formatter.

impl Default for NumThreads

fn default() -> NumThreads

Returns the “default value” for a type.

impl From<usize> for NumThreads

fn from(value: usize) -> NumThreads

Converts the nonnegative integer to number of threads as follows:

• 0 is converted to NumThreads::Auto,
• n is converted to NumThreads::Max(n) where n > 0.

impl PartialEq for NumThreads

fn eq(&self, other: &NumThreads) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for NumThreads

impl Eq for NumThreads

impl StructuralPartialEq for NumThreads