legate::Scope

class Scope

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