legate::PhysicalStore#

class PhysicalStore#

A multi-dimensional data container storing task data.

Public Functions

template<typename T, std::int32_t DIM, bool VALIDATE_TYPE = LEGATE_TRUE_WHEN_DEBUG> mdspan_type<const T, DIM> span_read_accessor( ) const#

Returns a read-only mdspan to the store over its entire domain. Equivalent to span_read_accessor<T, DIM>(shape<DIM>()).

Note

This API is experimental. It will eventually replace the Legion accessor interface, but we are seeking user feedback on it before such time. If you encounter issues, and/or have suggestions for improvements, please file a bug at nv-legate/legate#issues.

Template Parameters:

T – The element type of the mdspan.
DIM – The rank of the mdspan.
VALIDATE_TYPE – If true (default), checks that the type and rank of the mdspan match that of the PhysicalStore.

Returns:

The read-only mdspan accessor.

template<typename T, std::int32_t DIM, bool VALIDATE_TYPE = LEGATE_TRUE_WHEN_DEBUG> mdspan_type<T, DIM> span_write_accessor( )#

Returns a write-only mdspan to the store over its entire domain. Equivalent to span_write_accessor<T, DIM>(shape<DIM>()).

The user may read from a write-only accessor, but must write to the read-from location first, otherwise the returned values are undefined:

auto acc = store.span_write_accessor<float, 2>();

v = acc(0, 0); // Note: undefined value
acc(0, 0) = 42.0;
v = acc(0, 0); // OK, value will be 42.0

Note

Template Parameters:

T – The element type of the mdspan.
DIM – The rank of the mdspan.
VALIDATE_TYPE – If true (default on debug builds), checks that the type and rank of the mdspan match that of the PhysicalStore.

Returns:

The mdspan accessor.

template<typename T, std::int32_t DIM, bool VALIDATE_TYPE = LEGATE_TRUE_WHEN_DEBUG> mdspan_type<T, DIM> span_read_write_accessor( )#

Returns a read-write mdspan to the store over its entire domain. Equivalent to span_read_write_accessor<T, DIM>(shape<DIM>()).

Note

Template Parameters:

T – The element type of the mdspan.
DIM – The rank of the mdspan.
VALIDATE_TYPE – If true (default on debug builds), checks that the type and rank of the mdspan match that of the PhysicalStore.

Returns:

The mdspan accessor.

template<typename Redop, bool EXCLUSIVE, std::int32_t DIM, bool VALIDATE_TYPE = LEGATE_TRUE_WHEN_DEBUG> mdspan_type<typename Redop::LHS, DIM, detail::ReductionAccessor<Redop, EXCLUSIVE>> span_reduce_accessor( )#

Returns a reduction mdspan to the store over its entire domain. Equivalent to span_reduce_accessor<Redop, EXCLUSIVE, DIM>(shape<DIM>()).

Note

Template Parameters:

Redop – The reduction operator (e.g. SumReduction).
EXCLUSIVE – Whether the reduction accessor has exclusive access to the buffer.
DIM – The rank of the mdspan.
VALIDATE_TYPE – If true (default on debug builds), checks that the type and rank of the mdspan match that of the PhysicalStore.

Returns:

The mdspan accessor.

template<typename T, std::int32_t DIM, bool VALIDATE_TYPE = LEGATE_TRUE_WHEN_DEBUG> mdspan_type<const T, DIM> span_read_accessor( const Rect<DIM> &bounds ) const#

Returns a read-only mdspan to the store over the selected domain.

Note

If bounds is empty then the strides of the returned mdspan will be all 0 instead of what it might normally be. The object is still perfectly usable as normal but the strides will not be correct.

Template Parameters:

T – The element type of the mdspan.
DIM – The rank of the mdspan.
VALIDATE_TYPE – If true (default on debug builds), checks that the type and rank of the mdspan match that of the PhysicalStore.

Parameters:

bounds – The (sub-)domain over which to access the store.

Returns:

The mdspan accessor.

template<typename T, std::int32_t DIM, bool VALIDATE_TYPE = LEGATE_TRUE_WHEN_DEBUG> mdspan_type<T, DIM> span_write_accessor( const Rect<DIM> &bounds )#

Returns a write-only mdspan to the store over the selected domain.

The user may read from a write-only accessor, but must write to the read-from location first, otherwise the returned values are undefined:

auto acc = store.span_write_accessor<float, 2>(bounds);

v = acc(0, 0); // Note: undefined value
acc(0, 0) = 42.0;
v = acc(0, 0); // OK, value will be 42.0

Note

If bounds is empty then the strides of the returned mdspan will be all 0 instead of what it might normally be. The object is still perfectly usable as normal but the strides will not be correct.

Template Parameters:

T – The element type of the mdspan.
DIM – The rank of the mdspan.
VALIDATE_TYPE – If true (default on debug builds), checks that the type and rank of the mdspan match that of the PhysicalStore.

Parameters:

bounds – The (sub-)domain over which to access the store.

Returns:

The mdspan accessor.

template<typename T, std::int32_t DIM, bool VALIDATE_TYPE = LEGATE_TRUE_WHEN_DEBUG> mdspan_type<T, DIM> span_read_write_accessor( const Rect<DIM> &bounds )#

Returns a read-write mdspan to the store over the selected domain.

Note

If bounds is empty then the strides of the returned mdspan will be all 0 instead of what it might normally be. The object is still perfectly usable as normal but the strides will not be correct.

Template Parameters:

T – The element type of the mdspan.
DIM – The rank of the mdspan.
VALIDATE_TYPE – If true (default on debug builds), checks that the type and rank of the mdspan match that of the PhysicalStore.

Parameters:

bounds – The (sub-)domain over which to access the store.

Returns:

The mdspan accessor.

Returns a reduction mdspan to the store over the selected domain.

Note

If bounds is empty then the strides of the returned mdspan will be all 0 instead of what it might normally be. The object is still perfectly usable as normal but the strides will not be correct.

Template Parameters:

Redop – The reduction operator (e.g. SumReduction).
EXCLUSIVE – Whether the reduction accessor has exclusive access to the buffer.
DIM – The rank of the mdspan.
VALIDATE_TYPE – If true (default on debug builds), checks that the type and rank of the mdspan match that of the PhysicalStore.

Parameters:

bounds – The (sub-)domain over which to access the store.

Returns:

The mdspan accessor.

template<typename T, std::int32_t DIM, bool VALIDATE_TYPE = LEGATE_TRUE_WHEN_DEBUG> AccessorRO<T, DIM> read_accessor( ) const#

Returns a read-only accessor to the store for the entire domain.

Template Parameters:

T – Element type
DIM – Number of dimensions
VALIDATE_TYPE – If true (default), validates type and number of dimensions

Returns:

A read-only accessor to the store

template<typename T, std::int32_t DIM, bool VALIDATE_TYPE = LEGATE_TRUE_WHEN_DEBUG> AccessorWO<T, DIM> write_accessor( ) const#

Returns a write-only accessor to the store for the entire domain.

Template Parameters:

T – Element type
DIM – Number of dimensions
VALIDATE_TYPE – If true (default), validates type and number of dimensions

Returns:

A write-only accessor to the store

template<typename T, std::int32_t DIM, bool VALIDATE_TYPE = LEGATE_TRUE_WHEN_DEBUG> AccessorRW<T, DIM> read_write_accessor( ) const#

Returns a read-write accessor to the store for the entire domain.

Template Parameters:

T – Element type
DIM – Number of dimensions
VALIDATE_TYPE – If true (default), validates type and number of dimensions

Returns:

A read-write accessor to the store

template<typename OP, bool EXCLUSIVE, std::int32_t DIM, bool VALIDATE_TYPE = LEGATE_TRUE_WHEN_DEBUG> AccessorRD<OP, EXCLUSIVE, DIM> reduce_accessor( ) const#

Returns a reduction accessor to the store for the entire domain.

Template Parameters:

OP – Reduction operator class.
EXCLUSIVE – Indicates whether reductions can be performed in exclusive mode. If EXCLUSIVE is false, every reduction via the accessor is performed atomically.
DIM – Number of dimensions
VALIDATE_TYPE – If true (default), validates type and number of dimensions

Parameters:

bounds – Domain within which accesses should be allowed. The actual bounds for valid access are determined by an intersection between the store’s domain and the bounds.

Returns:

A reduction accessor to the store

template<typename VAL> VAL scalar() const#

Returns the scalar value stored in the store.

The requested type must match with the store’s data type. If the store is not backed by the future, the runtime will fail with an error message.

Template Parameters:: VAL – Type of the scalar value
Returns:: The scalar value stored in the store

template<typename T, std::int32_t DIM> Buffer<T, DIM> create_output_buffer( const Point<DIM> &extents, bool bind_buffer = false ) const#

Creates a Buffer of specified extents for the unbound store.

The returned Buffer is always consistent with the mapping policy for the store. Can be invoked multiple times unless bind_buffer is true.

Parameters:

extents – Extents of the Buffer
bind_buffer – If the value is true, the created Buffer will be bound to the store upon return

Returns:

A Buffer in which to write the output to.

TaskLocalBuffer create_output_buffer( const DomainPoint &extents, bool bind_buffer = false ) const#

Creates a TaskLocalBuffer of specified extents for the unbound store.

The returned TaskLocalBuffer is always consistent with the mapping policy for the store. Can be invoked multiple times unless bind_buffer is true.

Parameters:

extents – Extents of the TaskLocalBuffer
bind_buffer – If the value is true, the created TaskLocalBuffer will be bound to the store upon return.

Returns:

A TaskLocalBuffer in which to write the output to.

template<typename T, std::int32_t DIM> void bind_data( Buffer<T, DIM> &buffer, const Point<DIM> &extents ) const#

Binds a Buffer to the store.

Valid only when the store is unbound and has not yet been bound to another Buffer. The Buffer must be consistent with the mapping policy for the store. Recommend that the Buffer be created by a create_output_buffer() call.

Parameters:

buffer – Buffer to bind to the store
extents – Extents of the Buffer. Passing extents smaller than the actual extents of the Buffer is legal; the runtime uses the passed extents as the extents of this store.

void bind_data( const TaskLocalBuffer &buffer, const DomainPoint &extents, bool check_type = false ) const#

Binds a TaskLocalBuffer to the store.

Valid only when the store is unbound and has not yet been bound to another TaskLocalBuffer. The TaskLocalBuffer must be consistent with the mapping policy for the store. Recommend that the TaskLocalBuffer be created by a create_output_buffer() call.

Passing extents that are smaller than the actual extents of the TaskLocalBuffer is legal; the runtime uses the passed extents as the extents of this store.

If check_type is true, then buffer must have the same type as the PhysicalStore.

Parameters:

buffer – TaskLocalBuffer to bind to the store.
extents – Extents of the TaskLocalBuffer.
check_type – Whether to check the type of the buffer against the type of this store for validity.

Throws:

std::invalid_argument – If the type of buffer is not compatible with the type of the store (only thrown if check_type is true).

void bind_untyped_data( Buffer<std::int8_t, 1> &buffer, const Point<1> &extents ) const#

Binds a 1D Buffer of byte-size elements to the store in an untyped manner.

Values in the Buffer are reinterpreted based on the store’s actual type. The Buffer must have enough bytes to be aligned on the store’s element boundary. For example, a 1D Buffer of size 4 wouldn’t be valid if the store had the int64 type, whereas it would be if the store’s element type is int32.

Like the typed counterpart (i.e., bind_data()), the operation is legal only when the store is unbound and has not yet been bound to another buffer. The memory in which the buffer is created must be the same as the mapping decision of this store.

Can be used only with 1D unbound stores.

        constexpr auto num_elements      = 9;
        const auto element_size_in_bytes = store.type().size();
        constexpr auto UNTYPEED_DATA_DIM = 1;
        auto buffer = legate::create_buffer<std::int8_t, UNTYPEED_DATA_DIM>(num_elements *
                                                                            element_size_in_bytes);

        store.bind_untyped_data(buffer, legate::Point<UNTYPEED_DATA_DIM>{num_elements});

Parameters:

buffer – Buffer to bind to the store
extents – Extents of the buffer. Passing extents smaller than the actual extents of the buffer is legal; the runtime uses the passed extents as the extents of this store. The size of the buffer must be at least as big as extents * type().size().

void bind_empty_data() const#

Makes the unbound store empty.

Valid only when the store is unbound and has not yet been bound to another buffer.

std::int32_t dim() const#

Returns the dimension of the store.

Returns:: The store’s dimension

Type type() const#

Returns the type metadata of the store.

Returns:: The store’s Type

template<typename TYPE_CODE = Type::Code> inline TYPE_CODE code( ) const#

Returns the type code of the store.

Returns:: The store’s type code

template<std::int32_t DIM> Rect<DIM> shape() const#

Returns the store’s domain.

Returns:: Store’s domain

Domain domain() const#

Returns the store’s Domain

Returns:: Store’s Domain

InlineAllocation get_inline_allocation() const#

Returns a raw pointer and strides to the allocation.

Returns:: An InlineAllocation object holding a raw pointer and strides

mapping::StoreTarget target() const#

Returns the kind of memory where this PhysicalStore resides.

Throws:: std::invalid_argument – If this function is called on an unbound store
Returns:: The memory kind

bool is_readable() const#

Indicates whether the store can have a read accessor.

Returns:: true if the store can have a read accessor, false otherwise

bool is_writable() const#

Indicates whether the store can have a write accessor.

Returns:: true if the store can have a write accessor, false otherwise

bool is_reducible() const#

Indicates whether the store can have a reduction accessor.

Returns:: true if the store can have a reduction accessor, false otherwise

bool valid() const#

Indicates whether the store is valid.

A store passed to a task can be invalid only for reducer tasks for tree reduction. Otherwise, if the store is invalid, it cannot be used in any data access.

Returns:: true if the store is valid, false otherwise

bool transformed() const#

Indicates whether the store is transformed in any way.

Returns:: true if the store is transformed, false otherwise

bool is_future() const#

Indicates whether the store is backed by a future (i.e., a container for scalar value)

Returns:: true if the store is backed by a future, false otherwise

bool is_unbound_store() const#

Indicates whether the store is an unbound store.

The value DOES NOT indicate that the store has already assigned to a buffer; i.e., the store may have been assigned to a buffer even when this function returns true.

Returns:: true if the store is an unbound store, false otherwise

bool is_partitioned() const#

Indicates whether the store is partitioned.

Tasks sometimes need to know whether a given PhysicalStore is partitioned, i.e., corresponds to a subset of the (global) LogicalStore passed at the launch site. Unless the task explicitly requests broadcasting on the LogicalStore, the partitioning decision on the store is at the whim of the runtime. In this case, the task can use the is_partitioned() function to retrieve that information.

Returns:: true if the store is partitioned, false otherwise

std::unique_ptr<DLManagedTensorVersioned, void (*)(DLManagedTensorVersioned*)> to_dlpack( std::optional<bool> copy = std::nullopt, std::optional<CUstream_st*> stream = std::nullopt ) const#

Export this store into the DLPack format.

The value of copy has the following semantics:

true: Legate must copy the data. If Legate fails to copy the data, for any reason, an exception is thrown.
false: Legate must never copy the data. If the store cannot be exported without a copy, then an exception is thrown.
std::nullopt: Legate may copy the data if it is deemed necessary. Currently, this is never the case, and Legate will always provide a view.

In any case, if a copy is made, the DLManagedTensorVersioned::flags member will have the DLPACK_FLAG_BITMASK_IS_COPIED bit set.

The std::unique_ptr returned by this routine will automatically call the deleter of the DLPack tensor in its destructor.

Parameters:

copy – Whether to copy the underlying data or not.
stream – A stream on which the data must be coherent after this routine returns.

Returns:

The DLPack managed tensor.

PhysicalStore(const PhysicalArray &array)#

Constructs a store out of an array.

Throws:: std::invalid_argument – If the array is nullable or has sub-arrays