legate::Shape

class Shape

A class to express shapes of multi-dimensional entities in Legate.

Shape objects describe logical shapes, of multi-dimensional containers in Legate such as Legate arrays and Legate stores. For example, if the shape of a Legate store is (4, 2), the store is conceptually a 2D container having four rows and two columns of elements. The shape however does not entail any particular physical manifestation of the container. The aforementioned 2D store can be mapped to an allocation in which the elements of each row would be contiguously located or an allocation in which the elements of each column would be contiguously located.

A Shape object is essentially a tuple of extents, one for each dimension, and the dimensionality, i.e., the number of dimensions, is the size of this tuple. The volume of the Shape is a product of all the extents.

Since Legate allows containers’ shapes to be determined by tasks, some shapes may not be “ready” when the control code tries to introspect their extents. In this case, the control code will be blocked until the tasks updating the containers are complete. This asynchrony behind the shape objects is hidden from the control code and it’s recommended that introspection of the shapes of unbound arrays or stores should be avoided. The blocking behavior of each API call can be found in its reference (methods with no mention of blocking should exhibit no shape-related blocking).

Public Functions

Shape()

Constructs a 0D Shape

The constructed Shape is immediately ready

Equivalent to Shape({})

Shape(Span<const std::uint64_t> extents)

Constructs a Shape from a Span of extents.

The constructed Shape is immediately ready

Parameters:

extents – Dimension extents

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

Constructs a Shape from a tuple of extents.

The constructed Shape is immediately ready

Parameters:

extents – Dimension extents

explicit Shape(const std::vector<std::uint64_t> &extents)

Constructs a Shape from a std::vector of extents.

The constructed Shape is immediately ready

Parameters:

extents – Dimension extents

Shape(std::initializer_list<std::uint64_t> extents)

Constructs a Shape from a std::initializer_list of extents.

The constructed Shape is immediately ready

Parameters:

extents – Dimension extents

tuple<std::uint64_t> extents() const

Returns the Shape’s extents.

If the Shape is of an unbound array or store, the call blocks until the shape becomes ready.

Returns:

Dimension extents

std::size_t volume() const

Returns the Shape’s volume.

Equivalent to extents().volume(). If the Shape is of an unbound array or store, the call blocks until the Shape becomes ready.

Returns:

Volume of the Shape

std::uint32_t ndim() const

Returns the number of dimensions of this Shape

Unlike other Shape-related queries, this call is non-blocking.

Returns:

Number of dimensions

std::uint64_t operator[](std::uint32_t idx) const

Returns the extent of a given dimension.

If the Shape is of an unbound array or store, the call blocks until the Shape becomes ready. Unlike Shape::at(), this method does not check the dimension index.

Parameters:

idx – Dimension index

Returns:

Extent of the chosen dimension

std::uint64_t at(std::uint32_t idx) const

Returns the extent of a given dimension.

If the Shape is of an unbound array or store, the call blocks until the Shape becomes ready.

Parameters:

idx – Dimension index

Throws:

std::out_of_range – If the dimension index is invalid

Returns:

Extent of the chosen dimension

std::string to_string() const

Generates a human-readable string from the Shape (non-blocking)

Returns:

std::string generated from the Shape

bool operator==(const Shape &other) const

Checks if this Shape is the same as the given Shape

The equality check can block if one of the Shapes is of an unbound array or store and the other Shape is not of the same container.

Returns:

true if the Shapes are isomorphic, false otherwise

bool operator!=(const Shape &other) const

Checks if this Shape is different from the given Shape

The equality check can block if one of the Shapes is of an unbound array or store and the other Shape is not of the same container.

Returns:

true if the Shapes are different, false otherwise