tuning#

group Tuning

Classes and utilities to define tuning inside a Scope.

class ParallelPolicy

#include <legate/tuning/parallel_policy.h>

A helper class that describes parallelization policies for tasks.

A ParallelPolicy consists of knobs to control the parallelization policy for tasks in a given scope. To change the parallelization policy of the scope, a new Scope must be created with a ParallelPolicy. Currently, the ParallelPolicy class provides the following parameters:

streaming() (default: false): When the streaming() is true in a scope, the runtime executes the tasks in a streaming fashion. For example, if there are two tasks T1 and T2 in the scope, the normal execution would run all parallel instances of T1 before it would move on to T2’s, whereas the streaming execution would alternative between T1 and T2, launching a subset of parallel instances at a time that would fit to the memory. The granularity of tasks can be configured by the overdecompose_factor() (see below), and if the overdecompose_factor() is 1, no streaming would happen even if the streaming() is true.
overdecompose_factor() (default: 1): When the value is greater than 1, the auto-partitioner will over-decompose the stores when partitioning them; by default, the auto-partitioner creates N chunks in a store partition when there are N processors, but if the overdecompose_factor() is k in the scope, it would create kN chunks in the partition.

Public Functions

ParallelPolicy &with_streaming(bool streaming)

Sets the flag that indicates whether tasks in a given scope should be streamed.

Parameters:: streaming – A boolean value to set to the streaming flag.

ParallelPolicy &with_overdecompose_factor( std::uint32_t overdecompose_factor )

Sets the over-decomposing factor.

See also

set_overdecompose_factor.

Parameters:: overdecompose_factor – An over-decomposing factor.

inline bool streaming() const

Returns the streaming flag.

Returns:: true If the streaming is enabled.
Returns:: false If the streaming is not enabled.

inline std::uint32_t overdecompose_factor() const

Returns the over-decomposing factor.

Returns:: The over-decomposing factor.

bool operator==(const ParallelPolicy &other) const

Checks equality between ParallelPolicys.

Parameters:: other – A ParallelPolicy to compare this with.
Returns:: true If *this is the same as other
Returns:: false Otherwise.

bool operator!=(const ParallelPolicy &other) const

Checks inequality between ParallelPolicys.

Parameters:: other – A ParallelPolicy to compare this with.
Returns:: true If *this is different from other
Returns:: false Otherwise.

class Scope

#include <legate/tuning/scope.h>

A helper class to configure task execution.

The Scope class offers APIs to configure runtime parameters for task execution. The parameters set by a Scope object are effective only for the lifetime of the object. Currently, Scope can be used to configure the following parameters:

1) Task priority: Each task is associated with a priority value. The higher the value, the earlier among a set of ready-to-run tasks the task will get scheduled for execution. (the task with a higher priority, however, does not preempt another with a lower priority that is already running on the processor.) Task priorities are a signed 32-bit integer value. By default, all tasks get assigned to 0 for the priorities.

2) Provenance: User programs or libraries often want to attach provenance information to each of their operations and have it rendered in profiling outputs. Such information can be passed as a string via a Scope object, which then will be attached to all operations issued within the Scope’s lifetime.

3) Machine: By default, Legate operations target the entire machine available for the program. When a user program wants to assign a subset of the machine to its operations, it can subdivide the machine using the machine API (see Machine for details) and set a sub-machine for the scope using Scope. All operations within the lifetime of the Scope object can use only the sub-machine for their execution.

4) Parallelization policies: Legate has default policies to parallelize tasks, which the user program might want to override. In this case, the user program can set a new ParallelPolicy object to the scope to install new parallelization policies (see ParallelPolicy).

Each parameter can be set only once via each Scope object. Multiple attempts to set the same parameter would raise an exception.

Public Functions

Scope(): Constructs an empty Scope object.

explicit Scope(std::int32_t priority)

Constructs a Scope with a given task priority.

Equivalent to

auto scope = Scope();
scope.set_priority(priority);

Parameters:: priority – Task priority to set to the scope

explicit Scope(ExceptionMode exception_mode)

Constructs a Scope with a given exception mode.

Equivalent to

auto scope = Scope();
scope.set_exception_mode(exception_mode);

Parameters:: exception_mode – Exception mode to set to the scope

explicit Scope(std::string provenance)

Constructs a Scope with a given provenance string.

Equivalent to

auto scope = Scope();
scope.set_provenance(provenance);

Parameters:: provenance – Provenance string to set to the scope

explicit Scope(const mapping::Machine &machine)

Constructs a Scope with a given machine.

Equivalent to

auto scope = Scope();
scope.set_machine(machine);

The given machine is intersected with the machine from the outer scope

See also

set_machine

Parameters:: machine – Machine to use within the scope
Throws:: std::runtime_error – If the intersected machine is empty

explicit Scope(ParallelPolicy parallel_policy)

Constructs a Scope with a given parallel policy.

Equivalent to

auto scope = Scope();
scope.set_parallel_policy(parallel_policy);

See also

set_parallel_policy

Parameters:: parallel_policy – Parallel policy to use within the scope.

Scope &&with_priority(std::int32_t priority) &&

Sets a given task priority to the scope.

Parameters:: priority – Task priority to set to the scope
Throws:: std::invalid_argument – If a task priority has already been set via this Scope object

Scope &&with_exception_mode(ExceptionMode exception_mode) &&

Sets a given exception mode to the scope.

Parameters:: exception_mode – Exception mode to set to the scope
Throws:: std::invalid_argument – If an exception mode has already been set via this Scope object

Scope &&with_provenance(std::string provenance) &&

Sets a given provenance string to the scope.

Parameters:: provenance – Provenance string to set to the scope
Throws:: std::invalid_argument – If a provenance string has already been set via this Scope object

Scope &&with_machine(const mapping::Machine &machine) &&

Sets a given machine to the scope.

The given machine is intersected with the machine from the outer scope

See also

set_machine

Parameters:

machine – Machine to use within the scope

Throws:

std::runtime_error – If the intersected machine is empty
std::invalid_argument – If a machine has already been set via this Scope object

Scope &&with_parallel_policy(ParallelPolicy parallel_policy) &&

Sets a given parallel policy to the scope.

Parameters:: parallel_policy – Parallel policy to set to the scope.
Throws:: std::invalid_argument – If a parallel policy has already been set via this Scope object.
Returns:: Scope.

void set_priority(std::int32_t priority)

Sets a given task priority to the scope.

Parameters:: priority – Task priority to set to the scope
Throws:: std::invalid_argument – If a task priority has already been set via this Scope object

void set_exception_mode(ExceptionMode exception_mode)

Sets a given exception mode to the scope.

Parameters:: exception_mode – Exception mode to set to the scope
Throws:: std::invalid_argument – If an exception mode has already been set via this Scope object

void set_provenance(std::string provenance)

Sets a given provenance string to the scope.

Parameters:: provenance – Provenance string to set to the scope
Throws:: std::invalid_argument – If a provenance string has already been set via this Scope object

void set_machine(const mapping::Machine &machine)

Sets a given machine to the scope.

The given machine is intersected with the machine from the outer scope, so the actual machine used in this scope will always be a subset of the outer scope’s.

For example, if the machine of the current scope has GPUs 2, 3, 4, and 5, and a new scope is created with another machine with GPUs 3, 4, 5, and 6, then only the GPUs 3, 4, and 5 will be set to the new scope.

Parameters:

machine – Machine to use within the scope

Throws:

std::runtime_error – If the intersected machine is empty
std::invalid_argument – If a machine has already been set via this Scope object

void set_parallel_policy(ParallelPolicy parallel_policy)

Sets a given parallel policy to the scope.

Parameters:: parallel_policy – Parallel policy to set to the scope.
Throws:: std::invalid_argument – If a parallel policy has already been set via this Scope object.

Public Static Functions

static std::int32_t priority()

Returns the task priority of the current scope.

return Current task priority

static legate::ExceptionMode exception_mode()

Returns the exception mode of the current scope.

Returns:: Current exception mode

static std::string_view provenance()

Returns the provenance string of the current scope.

Returns:: Current provenance string

static mapping::Machine machine()

Returns the machine of the current scope.

Returns:: Current machine

static const ParallelPolicy &parallel_policy()

Returns the parallel policy of the current scope.

Returns:: Current parallel policy.

class Impl