Parallelism Class Reference

Detailed Description

Specifies a desired degree of parallelism for a parallelized operation.

This class denotes a specific number of threads; either 1 (no parallelism), a user-specified value (any number >= 1), or the maximum number. For convenience, conversion from bool is provided so that false is no parallelism and true is maximum parallelism.

Drake's API uses this class to allow users to control the degree of parallelism, regardless of how the parallelization is implemented (e.g., std::async, OpenMP, TBB, etc).

Configuring the process-wide maximum parallelism

The number of threads denoted by Parallelism::Max() is configurable with environment variables, but will be invariant within a single process. The first time it's accessed, the configured value will be latched into a global variable indefinitely. To ensure your configuration is obeyed, any changes to the environment variables that govern the max parallelism should be made prior to importing or calling any Drake code.

The following recipe determines the value that Parallelism::Max().num_threads() will report:

1. The default is the hardware limit from std::thread::hardware_concurrency(); this will be used when none of the special cases below are in effect.
2. If the environment variable DRAKE_NUM_THREADS is set to a positive integer less than hardware_concurrency(), the num_threads will be that value.
3. If the environment variable DRAKE_NUM_THREADS is not set but the environment variable OMP_NUM_THREADS is set to a positive integer less than hardware_concurrency(), the num_threads will be that value. (Note in particular that a comma-separated OMP_NUM_THREADS value will be ignored, even though that syntax might be valid for an OpenMP library).

The configuration recipe above does not require Drake to be built with OpenMP enabled. The inspection of OMP_NUM_THREADS as a configuration value is provided for convenience, regardless of whether OpenMP is enabled.

A note for Drake developers

In Drake's unit tests, DRAKE_NUM_THREADS is set to "1" by default. If your unit test requires actual parallelism, use the num_threads = N attribute in the BUILD.bazel file to declare a different value.

#include <drake/common/parallelism.h>

Public Member Functions
	Parallelism ()=default
	Default constructs with no parallelism (i.e., num_threads=1). More...
	Parallelism (bool parallelize)
	Constructs a Parallelism with either no parallelism (i.e., num_threads=1) or the maximum number of threads (Max()), as selected by parallelize. More...
	Parallelism (int num_threads)
	Constructs with the provided number of threads num_threads. More...
int	num_threads () const
	Returns the degree of parallelism. More...
Implements CopyConstructible, CopyAssignable, MoveConstructible, MoveAssignable
	Parallelism (const Parallelism &)=default
Parallelism &	operator= (const Parallelism &)=default
	Parallelism (Parallelism &&)=default
Parallelism &	operator= (Parallelism &&)=default

Static Public Member Functions
static Parallelism	None ()
	Constructs a Parallelism with no parallelism (i.e., num_threads=1). More...
static Parallelism	Max ()
	Constructs a Parallelism with the maximum number of threads. More...

Constructor & Destructor Documentation

Parallelism() [1/5]

Parallelism ( const Parallelism &  )

default

Parallelism() [2/5]

Parallelism ( Parallelism &&  )

default

Parallelism() [3/5]

Parallelism ( )

default

Default constructs with no parallelism (i.e., num_threads=1).

Parallelism() [4/5]

Parallelism

(

bool

parallelize

)

Constructs a Parallelism with either no parallelism (i.e., num_threads=1) or the maximum number of threads (Max()), as selected by parallelize.

This constructor allows for implicit conversion, for convenience.

Parallelism() [5/5]

Parallelism ( int  num_threads )

explicit

Constructs with the provided number of threads num_threads.

Precondition

num_threads >= 1.

Note

Constructing and using a Parallelism with num_threads greater than the actual hardware concurrency may result in fewer than the specified number of threads actually being launched or poor performance due to CPU contention.

Member Function Documentation

Max()

static Parallelism Max ( )

static

Constructs a Parallelism with the maximum number of threads.

Refer to the class overview documentation for how to configure the maximum.

None()

static Parallelism None ( )

static

Constructs a Parallelism with no parallelism (i.e., num_threads=1).

Python note: This function is not bound in pydrake (due to its name); instead, use the default constructor (or pass either 1 or False to the 1-argument constructor).

num_threads()

int num_threads

(

)

const

Returns the degree of parallelism.

The result will always be >= 1.

operator=() [1/2]

Parallelism& operator= ( const Parallelism &  )

default

operator=() [2/2]

Parallelism& operator= ( Parallelism &&  )

default

---

The documentation for this class was generated from the following file:

• drake/common/parallelism.h