legate::LogicalArray#

class LogicalArray#

A multi-dimensional array.

Subclassed by legate::ListLogicalArray, legate::StringLogicalArray

Public Functions

std::uint32_t dim() const#

Returns the number of dimensions of the array.

Returns:: The number of dimensions

Type type() const#

Returns the element type of the array.

Returns:: Type of elements in the store

Shape shape() const#

Returns the Shape of the array.

Returns:: The store’s Shape

const tuple<std::uint64_t> &extents() const#

Returns the extents of the array.

The call can block if the array is unbound

Returns:: The store’s extents

std::size_t volume() const#

Returns the number of elements in the array.

The call can block if the array is unbound

Returns:: The number of elements in the store

bool unbound() const#

Indicates whether the array is unbound.

Returns:: true if the array is unbound, false if it is normal

bool nullable() const#

Indicates whether the array is nullable.

Returns:: true if the array is nullable, false otherwise

bool nested() const#

Indicates whether the array has child arrays.

Returns:: true if the array has child arrays, false otherwise

std::uint32_t num_children() const#

Returns the number of child sub-arrays.

Returns:: Number of child sub-arrays

LogicalArray promote( std::int32_t extra_dim, std::size_t dim_size ) const#

Adds an extra dimension to the array.

The call can block if the array is unbound

Parameters:

extra_dim – Position for a new dimension
dim_size – Extent of the new dimension

Throws:

std::invalid_argument – When extra_dim is not a valid dimension name
std::runtime_error – If the array or any of the sub-arrays is a list array

Returns:

A new array with an extra dimension

LogicalArray project(std::int32_t dim, std::int64_t index) const#

Projects out a dimension of the array.

The call can block if the array is unbound

Parameters:

dim – Dimension to project out
index – Index on the chosen dimension

Throws:

std::invalid_argument – If dim is not a valid dimension name or index is out of bounds
std::runtime_error – If the array or any of the sub-arrays is a list array

Returns:

A new array with one fewer dimension

LogicalArray slice(std::int32_t dim, Slice sl) const#

Slices a contiguous sub-section of the array.

The call can block if the array is unbound

Parameters:

dim – Dimension to slice
sl – Slice descriptor

Throws:

std::invalid_argument – If dim is not a valid dimension name
std::runtime_error – If the array or any of the sub-arrays is a list array

Returns:

A new array that corresponds to the sliced section

LogicalArray transpose(const std::vector<std::int32_t> &axes) const#

Reorders dimensions of the array.

The call can block if the array is unbound

Parameters:

axes – Mapping from dimensions of the resulting array to those of the input

Throws:

std::invalid_argument – If any of the following happens: 1) The length of axes doesn’t match the array’s dimension; 2) axes has duplicates; 3) Any axis in axes is an invalid axis name.
std::runtime_error – If the array or any of the sub-arrays is a list array

Returns:

A new array with the dimensions transposed

LogicalArray delinearize( std::int32_t dim, const std::vector<std::uint64_t> &sizes ) const#

Delinearizes a dimension into multiple dimensions.

The call can block if the array is unbound

Parameters:

dim – Dimension to delinearize
sizes – Extents for the resulting dimensions

Throws:

std::invalid_argument – If dim is invalid for the array or sizes does not preserve the extent of the chosen dimension
std::runtime_error – If the array or any of the sub-arrays is a list array

Returns:

A new array with the chosen dimension delinearized

LogicalStore data() const#

Returns the store of this array.

Returns:: LogicalStore

LogicalStore null_mask() const#

Returns the null mask of this array.

Returns:: LogicalStore

LogicalArray child(std::uint32_t index) const#

Returns the sub-array of a given index.

Parameters:

index – Sub-array index

Throws:

std::invalid_argument – If the array has no child arrays, or the array is an unbound struct array
std::out_of_range – If the index is out of range

Returns:

LogicalArray

PhysicalArray get_physical_array( std::optional<mapping::StoreTarget> target = std::nullopt ) const#

Creates a PhysicalArray for this LogicalArray

This call blocks the client’s control flow and fetches the data for the whole array to the current node.

When the target is StoreTarget::FBMEM, the data will be consolidated in the framebuffer of the first GPU available in the scope.

If no target is given, the runtime uses StoreTarget::SOCKETMEM if it exists and StoreTarget::SYSMEM otherwise.

If there already exists a physical array for a different memory target, that physical array will be unmapped from memory and become invalid to access.

Parameters:: target – The type of memory in which the physical array would be created.
Throws:: std::invalid_argument – If no memory of the chosen type is available
Returns:: A PhysicalArray of the LogicalArray

ListLogicalArray as_list_array() const#

Casts this array as a ListLogicalArray

Throws:: std::invalid_argument – If the array is not a list array
Returns:: The array as a ListLogicalArray

StringLogicalArray as_string_array() const#

Casts this array as a StringLogicalArray

Throws:: std::invalid_argument – If the array is not a string array
Returns:: The array as a StringLogicalArray

void offload_to(mapping::StoreTarget target_mem) const#

Offload array to specified target memory.

Copies the array to the specified memory, if necessary, and marks it as the most up-to-date copy, allowing the runtime to discard any copies in other memories.

Main usage is to free up space in one kind of memory by offloading resident arrays and stores to another kind of memory. For example, after a GPU task that reads or writes to an array, users can manually free up Legate’s GPU memory by offloading the array to host memory.

All the stores that comprise the array are offloaded, i.e., the data store, the null mask, and child arrays, etc.

Currently, the runtime does not validate if the target memory has enough capacity or free space at the point of launching or executing the offload operation. The program will most likely crash if there isn’t enough space in the target memory. The user is therefore encouraged to offload to a memory type that is likely to have sufficient space.

This should not be treated as a prefetch call as it offers little benefit to that end. The runtime will ensure that data for a task is resident in the required memory before the task begins executing.

If this array is backed by another array, e.g., if this array is a slice or some other transform of another array, then both the arrays will be offloaded due to being backed by the same memory.

  // This snippet launches two GPU tasks that manipulate two different stores,
  // where each store occupies more than 50% of GPU memory. Runtime can map and
  // schedule both the tasks at the same time. Without offloading the first store,
  // mapping will fail for the second task. Therefore, we insert an `offload_to`
  // call for the first store after submitting the first task and before submitting
  // the second task.
  {
    auto task1 = runtime->create_task(library, GPUonlyTask::TASK_CONFIG.task_id());

    task1.add_output(store1);
    runtime->submit(std::move(task1));
  }

  store1.offload_to(legate::mapping::StoreTarget::SYSMEM);

  {
    auto task2 = runtime->create_task(library, GPUonlyTask::TASK_CONFIG.task_id());

    task2.add_output(store2);
    runtime->submit(std::move(task2));
  }

Parameters:: target_mem – The target memory.
Throws:: std::invalid_argument – If Legate was not configured to support target_mem.

class Impl#