legate::Shape#
-
class Shape#
A class to express shapes of multi-dimensional entities in Legate.
Shapeobjects 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
Shapeobject 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 theShapeis 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
-
inline Shape()#
Constructs a 0D
ShapeThe constructed
Shapeis immediately readyEquivalent to
Shape({})
-
Shape(tuple<std::uint64_t> extents)#
Constructs a
Shapefrom atupleof extents.The constructed
Shapeis immediately ready- Parameters:
extents – Dimension extents
-
inline explicit Shape(std::vector<std::uint64_t> extents)#
Constructs a
Shapefrom astd::vectorof extents.The constructed
Shapeis immediately ready- Parameters:
extents – Dimension extents
-
inline Shape(std::initializer_list<std::uint64_t> extents)#
Constructs a
Shapefrom astd::initializer_listof extents.The constructed
Shapeis immediately ready- Parameters:
extents – Dimension extents
-
const tuple<std::uint64_t> &extents() const#
Returns the
Shape’s extents.If the
Shapeis 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 theShapeis of an unbound array or store, the call blocks until theShapebecomes ready.- Returns:
Volume of the
Shape
-
std::uint32_t ndim() const#
Returns the number of dimensions of this
ShapeUnlike other
Shape-related queries, this call is non-blocking.- Returns:
Number of dimensions
-
inline std::uint64_t operator[](std::uint32_t idx) const#
Returns the extent of a given dimension.
If the
Shapeis of an unbound array or store, the call blocks until theShapebecomes ready. UnlikeShape::at(), this method does not check the dimension index.- Parameters:
idx – Dimension index
- Returns:
Extent of the chosen dimension
-
inline std::uint64_t at(std::uint32_t idx) const#
Returns the extent of a given dimension.
If the
Shapeis of an unbound array or store, the call blocks until theShapebecomes 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::stringgenerated from theShape
-
inline Shape()#