legate::Runtime#

class Runtime#

Class that implements the Legate runtime.

The legate runtime provides common services, including as library registration, store creation, operator creation and submission, resource management and scoping, and communicator management. Legate libraries are free of all these details about distribute programming and can focus on their domain logics.

Public Functions

Library create_library(
std::string_view library_name,
const ResourceConfig &config = ResourceConfig{},
std::unique_ptr<mapping::Mapper> mapper = nullptr,
std::map<VariantCode, VariantOptions> default_options = {}
)#

Creates a library.

A library is a collection of tasks and custom reduction operators. The maximum number of tasks and reduction operators can be optionally specified with a ResourceConfig object. Each library can optionally have a mapper that specifies mapping policies for its tasks. When no mapper is given, the default mapper is used.

Parameters:

  • library_name – Library name. Must be unique to this library

  • config – Optional configuration object

  • mapper – Optional mapper object

  • default_options – Optional default task variant options

Throws:

std::invalid_argument – If a library already exists for a given name

Returns:

Library object

Library find_library(std::string_view library_name) const#

Finds a library.

Parameters:

library_name – Library name

Throws:

std::out_of_range – If no library is found for a given name

Returns:

Library object

std::optional<Library> maybe_find_library(
std::string_view library_name
) const#

Attempts to find a library.

If no library exists for a given name, a null value will be returned

Parameters:

library_name – Library name

Returns:

Library object if a library exists for a given name, a null object otherwise

Library find_or_create_library(
std::string_view library_name,
const ResourceConfig &config = ResourceConfig{},
std::unique_ptr<mapping::Mapper> mapper = nullptr,
const std::map<VariantCode, VariantOptions> &default_options = {},
bool *created = nullptr
)#

Finds or creates a library.

The optional configuration and mapper objects are picked up only when the library is created.

Parameters:

  • library_name – Library name. Must be unique to this library

  • config – Optional configuration object

  • mapper – Optional mapper object

  • default_options – Optional default task variant options

  • created – Optional pointer to a boolean flag indicating whether the library has been created because of this call

Returns:

Context object for the library

AutoTask create_task(Library library, LocalTaskID task_id)#

Creates an AutoTask.

Parameters:

  • library – Library to query the task

  • task_id – Library-local Task ID

Returns:

Task object

ManualTask create_task(
Library library,
LocalTaskID task_id,
const tuple<std::uint64_t> &launch_shape
)#

Creates a ManualTask.

Parameters:

  • library – Library to query the task

  • task_id – Library-local Task ID

  • launch_shape – Launch domain for the task

Returns:

Task object

ManualTask create_task(
Library library,
LocalTaskID task_id,
const Domain &launch_domain
)#

Creates a ManualTask.

This overload should be used when the lower bounds of the task’s launch domain should be non-zero. Note that the upper bounds of the launch domain are inclusive (whereas the launch_shape in the other overload is exclusive).

Parameters:

  • library – Library to query the task

  • task_id – Library-local Task ID

  • launch_domain – Launch domain for the task

Returns:

Task object

void issue_copy(
LogicalStore &target,
const LogicalStore &source,
std::optional<ReductionOpKind> redop_kind = std::nullopt
)#

Issues a copy between stores.

The source and target stores must have the same shape.

Parameters:

  • target – Copy target

  • source – Copy source

  • redop_kind – ID of the reduction operator to use (optional). The store’s type must support the operator.

Throws:

std::invalid_argument – If the store’s type doesn’t support the reduction operator

void issue_copy(
LogicalStore &target,
const LogicalStore &source,
std::optional<std::int32_t> redop_kind
)#

Issues a copy between stores.

The source and target stores must have the same shape.

Parameters:

  • target – Copy target

  • source – Copy source

  • redop_kind – ID of the reduction operator to use (optional). The store’s type must support the operator.

Throws:

std::invalid_argument – If the store’s type doesn’t support the reduction operator

void issue_gather(
LogicalStore &target,
const LogicalStore &source,
const LogicalStore &source_indirect,
std::optional<ReductionOpKind> redop_kind = std::nullopt
)#

Issues a gather copy between stores.

The indirection store and the target store must have the same shape.

Parameters:

  • target – Copy target

  • source – Copy source

  • source_indirect – Store for source indirection

  • redop_kind – ID of the reduction operator to use (optional). The store’s type must support the operator.

Throws:

std::invalid_argument – If the store’s type doesn’t support the reduction operator

void issue_gather(
LogicalStore &target,
const LogicalStore &source,
const LogicalStore &source_indirect,
std::optional<std::int32_t> redop_kind
)#

Issues a gather copy between stores.

The indirection store and the target store must have the same shape.

Parameters:

  • target – Copy target

  • source – Copy source

  • source_indirect – Store for source indirection

  • redop_kind – ID of the reduction operator to use (optional). The store’s type must support the operator.

Throws:

std::invalid_argument – If the store’s type doesn’t support the reduction operator

void issue_scatter(
LogicalStore &target,
const LogicalStore &target_indirect,
const LogicalStore &source,
std::optional<ReductionOpKind> redop_kind = std::nullopt
)#

Issues a scatter copy between stores.

The indirection store and the source store must have the same shape.

Parameters:

  • target – Copy target

  • target_indirect – Store for target indirection

  • source – Copy source

  • redop_kind – ID of the reduction operator to use (optional). The store’s type must support the operator.

Throws:

std::invalid_argument – If the store’s type doesn’t support the reduction operator

void issue_scatter(
LogicalStore &target,
const LogicalStore &target_indirect,
const LogicalStore &source,
std::optional<std::int32_t> redop_kind
)#

Issues a scatter copy between stores.

The indirection store and the source store must have the same shape.

Parameters:

  • target – Copy target

  • target_indirect – Store for target indirection

  • source – Copy source

  • redop_kind – ID of the reduction operator to use (optional). The store’s type must support the operator.

Throws:

std::invalid_argument – If the store’s type doesn’t support the reduction operator

void issue_scatter_gather(
LogicalStore &target,
const LogicalStore &target_indirect,
const LogicalStore &source,
const LogicalStore &source_indirect,
std::optional<ReductionOpKind> redop_kind = std::nullopt
)#

Issues a scatter-gather copy between stores.

The indirection stores must have the same shape.

Parameters:

  • target – Copy target

  • target_indirect – Store for target indirection

  • source – Copy source

  • source_indirect – Store for source indirection

  • redop_kind – ID of the reduction operator to use (optional). The store’s type must support the operator.

Throws:

std::invalid_argument – If the store’s type doesn’t support the reduction operator

void issue_scatter_gather(
LogicalStore &target,
const LogicalStore &target_indirect,
const LogicalStore &source,
const LogicalStore &source_indirect,
std::optional<std::int32_t> redop_kind
)#

Issues a scatter-gather copy between stores.

The indirection stores must have the same shape.

Parameters:

  • target – Copy target

  • target_indirect – Store for target indirection

  • source – Copy source

  • source_indirect – Store for source indirection

  • redop_kind – ID of the reduction operator to use (optional). The store’s type must support the operator.

Throws:

std::invalid_argument – If the store’s type doesn’t support the reduction operator

void issue_fill(const LogicalArray &lhs, const LogicalStore &value)#

Fills a given array with a constant.

Parameters:

  • lhs – Logical array to fill

  • value – Logical store that contains the constant value to fill the array with

void issue_fill(const LogicalArray &lhs, const Scalar &value)#

Fills a given array with a constant.

Parameters:

  • lhs – Logical array to fill

  • value – Value to fill the array with

LogicalStore tree_reduce(
Library library,
LocalTaskID task_id,
const LogicalStore &store,
std::int32_t radix = 4
)#

Performs reduction on a given store via a task.

Parameters:

  • library – The library for the reducer task

  • task_id – reduction task ID

  • store – Logical store to reduce

  • radix – Optional radix value that determines the maximum number of input stores to the task at each reduction step

void submit(AutoTask &&task)#

Submits an AutoTask for execution.

Each submitted operation goes through multiple pipeline steps to eventually get scheduled for execution. It’s not guaranteed that the submitted operation starts executing immediately.

The runtime takes the ownership of the submitted task. Once submitted, the task becomes invalid and is not reusable.

Parameters:

task – An AutoTask to execute

void submit(ManualTask &&task)#

Submits a ManualTask for execution.

Each submitted operation goes through multiple pipeline steps to eventually get scheduled for execution. It’s not guaranteed that the submitted operation starts executing immediately.

The runtime takes the ownership of the submitted task. Once submitted, the task becomes invalid and is not reusable.

Parameters:

task – A ManualTask to execute

LogicalArray create_array(
const Type &type,
std::uint32_t dim = 1,
bool nullable = false
)#

Creates an unbound array.

Parameters:

  • type – Element type

  • dim – Number of dimensions

  • nullable – Nullability of the array

Returns:

Logical array

LogicalArray create_array(
const Shape &shape,
const Type &type,
bool nullable = false,
bool optimize_scalar = false
)#

Creates a normal array.

Parameters:

  • shape – Shape of the array. The call does not block on this shape

  • type – Element type

  • nullable – Nullability of the array

  • optimize_scalar – When true, the runtime internally uses futures optimized for storing scalars

Returns:

Logical array

LogicalArray create_array_like(
const LogicalArray &to_mirror,
std::optional<Type> type = std::nullopt
)#

Creates an array isomorphic to the given array.

Parameters:

  • to_mirror – The array whose shape would be used to create the output array. The call does not block on the array’s shape.

  • type – Optional type for the resulting array. Must be compatible with the input array’s type

Returns:

Logical array isomorphic to the input

StringLogicalArray create_string_array(
const LogicalArray &descriptor,
const LogicalArray &vardata
)#

Creates a string array from the existing sub-arrays.

The caller is responsible for making sure that the vardata sub-array is valid for all the descriptors in the descriptor sub-array

Parameters:

  • descriptor – Sub-array for descriptors

  • vardata – Sub-array for characters

Throws:

std::invalid_argument – When any of the following is true: 1) descriptor or vardata is unbound or N-D where N > 1 2) descriptor does not have a 1D rect type 3) vardata is nullable 4) vardata does not have an int8 type

Returns:

String logical array

ListLogicalArray create_list_array(
const LogicalArray &descriptor,
const LogicalArray &vardata,
std::optional<Type> type = std::nullopt
)#

Creates a list array from the existing sub-arrays.

The caller is responsible for making sure that the vardata sub-array is valid for all the descriptors in the descriptor sub-array

Parameters:

  • descriptor – Sub-array for descriptors

  • vardata – Sub-array for vardata

  • type – Optional list type the returned array would have

Throws:

std::invalid_argument – When any of the following is true: 1) type is not a list type 2) descriptor or vardata is unbound or N-D where N > 1 3) descriptor does not have a 1D rect type 4) vardata is nullable 5) vardata and type have different element types

Returns:

List logical array

LogicalStore create_store(const Type &type, std::uint32_t dim = 1)#

Creates an unbound store.

Parameters:

  • type – Element type

  • dim – Number of dimensions of the store

Returns:

Logical store

LogicalStore create_store(
const Shape &shape,
const Type &type,
bool optimize_scalar = false
)#

Creates a normal store.

Parameters:

  • shape – Shape of the store. The call does not block on this shape.

  • type – Element type

  • optimize_scalar – When true, the runtime internally uses futures optimized for storing scalars

Returns:

Logical store

LogicalStore create_store(
const Scalar &scalar,
const Shape &shape = Shape{1}
)#

Creates a normal store out of a Scalar object.

Parameters:

  • scalar – Value of the scalar to create a store with

  • shape – Shape of the store. The volume must be 1. The call does not block on this shape.

Returns:

Logical store

LogicalStore create_store(
const Shape &shape,
const Type &type,
void *buffer,
bool read_only = true,
const mapping::DimOrdering &ordering = mapping::DimOrdering::c_order()
)#

Creates a store by attaching to an existing allocation.

See also

legate::ExternalAllocation For important instructions regarding the mutability and lifetime management of the attached allocation.

Parameters:

  • shape – Shape of the store. The call does not block on this shape.

  • type – Element type.

  • buffer – Pointer to the beginning of the allocation to attach to; allocation must be contiguous, and cover the entire contents of the store (at least extents.volume() * type.size() bytes).

  • read_only – Whether the allocation is read-only.

  • ordering – In what order the elements are laid out in the passed buffer.

Returns:

Logical store.

LogicalStore create_store(
const Shape &shape,
const Type &type,
const ExternalAllocation &allocation,
const mapping::DimOrdering &ordering = mapping::DimOrdering::c_order()
)#

Creates a store by attaching to an existing allocation.

See also

legate::ExternalAllocation For important instructions regarding the mutability and lifetime management of the attached allocation.

Parameters:

  • shape – Shape of the store. The call does not block on this shape.

  • type – Element type.

  • allocation – External allocation descriptor.

  • ordering – In what order the elements are laid out in the passed allocation.

Returns:

Logical store.

std::pair<LogicalStore, LogicalStorePartition> create_store(
const Shape &shape,
const tuple<std::uint64_t> &tile_shape,
const Type &type,
const std::vector<std::pair<ExternalAllocation, tuple<std::uint64_t>>> &allocations,
const mapping::DimOrdering &ordering = mapping::DimOrdering::c_order()
)#

Creates a store by attaching to multiple existing allocations.

External allocations must be read-only.

See also

legate::ExternalAllocation For important instructions regarding the mutability and lifetime management of the attached allocation.

Parameters:

  • shape – Shape of the store. The call can BLOCK on this shape for constructing a store partition.

  • tile_shape – Shape of tiles.

  • type – Element type.

  • allocations – Pairs of external allocation descriptors and sub-store colors.

  • ordering – In what order the elements are laid out in the passed allocatios.

Throws:

std::invalid_argument – If any of the external allocations are not read-only.

Returns:

A pair of a logical store and its partition.

void prefetch_bloated_instances(
const LogicalStore &store,
tuple<std::uint64_t> low_offsets,
tuple<std::uint64_t> high_offsets,
bool initialize = false
)#

Gives the runtime a hint that the store can benefit from bloated instances.

The runtime currently does not look ahead in the task stream to recognize that a given set of tasks can benefit from the ahead-of-time creation of “bloated” instances encompassing multiple slices of a store. This means that the runtime will construct bloated instances incrementally and completely only when it sees all the slices, resulting in intermediate instances that (temporarily) increases the memory footprint. This function can be used to give the runtime a hint ahead of time about the bloated instances, which would be reused by the downstream tasks without going through the same incremental process.

For example, let’s say we have a 1-D store A of size 10 and we want to partition A across two GPUs. By default, A would be partitioned equally and each GPU gets an instance of size 5. Suppose we now have a task that aligns two slices A[1:10] and A[:9]. The runtime would partition the slices such that the task running on the first GPU gets A[1:6] and A[:5], and the task running on the second GPU gets A[6:] and A[5:9]. Since the original instance on the first GPU does not cover the element A[5] included in the first slice A[1:6], the mapper needs to create a new instance for A[:6] that encompasses both of the slices, leading to an extra copy. In this case, if the code calls prefetch(A, {0}, {1}) to pre-alloate instances that contain one extra element on the right before it uses A, the extra copy can be avoided.

A couple of notes about the API:

  • Unless initialize is true, the runtime assumes that the store has been initialized. Passing an uninitialized store would lead to a runtime error.

  • If the store has pre-existing instances, the runtime may combine those with the bloated instances if such combination is deemed desirable.

Note

This API is experimental

Parameters:

  • store – Store to create bloated instances for

  • low_offsets – Offsets to bloat towards the negative direction

  • high_offsets – Offsets to bloat towards the positive direction

  • initialize – If true, the runtime will issue a fill on the store to initialize it. The default value is false

void issue_mapping_fence()#

Issues a mapping fence.

A mapping fence, when issued, blocks mapping of all downstream operations before those preceding the fence get mapped. An issue_mapping_fence call returns immediately after the request is submitted to the runtime, and the fence asynchronously goes through the runtime analysis pipeline just like any other Legate operations. The call also flushes the scheduling window for batched execution.

Mapping fences only affect how the operations are mapped and do not change their execution order, so they are semantically no-op. Nevertheless, they are sometimes useful when the user wants to control how the resource is consumed by independent tasks. Consider a program with two independent tasks A and B, both of which discard their stores right after their execution. If the stores are too big to be allocated all at once, mapping A and B in parallel (which can happen because A and B are independent and thus nothing stops them from getting mapped concurrently) can lead to a failure. If a mapping fence exists between the two, the runtime serializes their mapping and can reclaim the memory space from stores that would be discarded after A’s execution to create allocations for B.

void issue_execution_fence(bool block = false)#

Issues an execution fence.

An execution fence is a join point in the task graph. All operations prior to a fence must finish before any of the subsequent operations start.

All execution fences are mapping fences by definition; i.e., an execution fence not only prevents the downstream operations from being mapped ahead of itself but also precedes their execution.

Parameters:

block – When true, the control code blocks on the fence and all operations that have been submitted prior to this fence.

void raise_pending_exception()#

Raises a pending exception.

When the exception mode of a scope is “deferred” (i.e., Scope::exception_mode() == ExceptionMode::DEFERRED), the exceptions from tasks in the scope are not immediately handled, but are pushed to the pending exception queue. Accumulated pending exceptions are not flushed until raise_pending_exception is invoked. The function throws the first exception in the pending exception queue and clears the queue. If there is no pending exception to be raised, the function does nothing.

Throws:

legate::TaskException – When there is a pending exception to raise

std::uint32_t node_count() const#

Returns the total number of nodes.

Returns:

Total number of nodes

std::uint32_t node_id() const#

Returns the current rank.

Returns:

Rank ID

mapping::Machine get_machine() const#

Returns the machine of the current scope.

Returns:

Machine object

Processor get_executing_processor() const#

Returns the current Processor on which the caller is executing.

Returns:

The current Processor.

void start_profiling_range()#

Start a Legion profiling range.

void stop_profiling_range(std::string_view provenance)#

Stop a Legion profiling range.

Parameters:

provenance – User-supplied provenance string

Public Static Functions

static Runtime *get_runtime()#

Returns a singleton runtime object.

Returns:

The runtime object