legate::mapping::Machine#

class Machine#

Machine descriptor class.

A Machine object describes the machine resource that should be used for a given scope of execution. By default, the scope is given the entire machine resource configured for this process. Then, the client can limit the resource by extracting a portion of the machine and setting it for the scope using MachineTracker. Configuring the scope with an empty machine raises a std::runtime_error exception.

Public Functions

TaskTarget preferred_target() const#

Preferred processor type of this machine descriptor.

The preferred target of a machine is used to determine which task variant is launched in case there are multiple possibilities. For example, a machine might have both CPUs and GPUs, in which case the preferred target would select one of them.

Returns:

Task target

ProcessorRange processor_range() const#

Returns the processor range for the preferred processor type in this descriptor.

Returns:

A processor range `

ProcessorRange processor_range(TaskTarget target) const#

Returns the processor range for a given processor type.

If the processor type does not exist in the descriptor, an empty range is returned

Parameters:

target – Processor type to query

Returns:

A processor range

Span<const TaskTarget> valid_targets() const#

Returns the valid task targets within this machine descriptor.

Returns:

Task targets

std::vector<TaskTarget> valid_targets_except(
const std::set<TaskTarget> &to_exclude
) const#

Returns the valid task targets excluding a given set of targets.

Parameters:

to_exclude – Task targets to exclude from the query

Returns:

Task targets

std::uint32_t count() const#

Returns the number of preferred processors.

Returns:

Processor count

std::uint32_t count(TaskTarget target) const#

Returns the number of processors of a given type.

Parameters:

target – Processor type to query

Returns:

Processor count

std::string to_string() const#

Converts the machine descriptor to a human-readable string.

Returns:

Machine descriptor in a string

Machine only(TaskTarget target) const#

Extracts the processor range for a given processor type and creates a fresh machine descriptor with it.

If the target does not exist in the machine descriptor, an empty descriptor is returned.

Parameters:

target – Processor type to select

Returns:

Machine descriptor with the chosen processor range

Machine only(Span<const TaskTarget> targets) const#

Extracts the processor ranges for a given set of processor types and creates a fresh machine descriptor with them.

Any of the targets that does not exist will be mapped to an empty processor range in the returned machine descriptor

The preferred target of the new machine is chosen based on the following criteria:

  • If targets is empty, the preferred target of the source machine is used.

  • If targets is not empty:

    • The first target that produces a non-empty processor range (from the source machine) according to the numerical ordering of the TaskTarget enum is used. For example, if the source machine has 2 CPUs, 0 OMPs, and 2 GPUs, and targets = {OMP, CPU, GPU}, then the preferred target will be GPU because:

      • OMP had an empty processor range.

      • GPU has higher precedence over CPU.

    • If all of the targets produced an empty processor range (and therefore the resulting Machine is empty), then the highest priority entry in targets is used. For example, if a machine has 0 CPUs and 0 GPUs, and targets = {CPU, GPU}, then the preferred target will be GPU because GPU has precedence over CPU.

Parameters:

targets – Processor types to select

Returns:

Machine descriptor with the chosen processor ranges

Machine slice(
std::uint32_t from,
std::uint32_t to,
TaskTarget target,
bool keep_others = false
) const#

Slices the processor range for a given processor type.

Parameters:

  • from – Starting index

  • to – End index

  • target – Processor type to slice

  • keep_others – Optional flag to keep unsliced ranges in the returned machine descriptor

Returns:

Machine descriptor with the chosen procssor range sliced

Machine slice(
std::uint32_t from,
std::uint32_t to,
bool keep_others = false
) const#

Slices the processor range for the preferred processor type of this machine descriptor.

Parameters:

  • from – Starting index

  • to – End index

  • keep_others – Optional flag to keep unsliced ranges in the returned machine descriptor

Returns:

Machine descriptor with the preferred processor range sliced

Machine operator[](TaskTarget target) const#

Selects the processor range for a given processor type and constructs a machine descriptor with it.

This yields the same result as .only(target).

Parameters:

target – Processor type to select

Returns:

Machine descriptor with the chosen processor range

Machine operator[](Span<const TaskTarget> targets) const#

Selects the processor ranges for a given set of processor types and constructs a machine descriptor with them.

This yields the same result as .only(targets).

Parameters:

targets – Processor types to select

Returns:

Machine descriptor with the chosen processor ranges

Machine operator&(const Machine &other) const#

Computes an intersection between two machine descriptors.

Parameters:

other – Machine descriptor to intersect with this descriptor

Returns:

Machine descriptor

bool empty() const#

Indicates whether the machine descriptor is empty.

A machine descriptor is empty when all its processor ranges are empty

Returns:

true The machine descriptor is empty

Returns:

false The machine descriptor is non-empty