legate::Scalar

class Scalar

A type-erased container for scalars.

A Scalar can be owned or shared, depending on whether it owns the backing allocation: If a Scalar is shared, it does not own the allocation and any of its copies are also shared. If a Scalar is owned, it owns the backing allocation and releases it upon destruction. Any copy of an owned Scalar is owned as well.

Public Functions

Scalar()

Creates a null scalar.

See also

null()

Scalar(const Type &type, const void *data, bool copy = false)

Creates a shared Scalar with an existing allocation. The caller is responsible for passing in a sufficiently big allocation.

Parameters:

• type – Type of the scalar

• data – Allocation containing the data.

• copy – If true, the scalar copies the data stored in the allocation and becomes owned.

template<typename T, typename = std::enable_if_t<!std::is_convertible_v<T, std::string> && !std::is_same_v<std::decay_t<T>, InternalSharedPtr<detail::Scalar>>>>
explicit Scalar(

const T &value

)

Creates an owned Scalar from a scalar value.

Template Parameters:

T – The scalar type to wrap

Parameters:

value – A scalar value to create a Scalar with

template<typename T>
Scalar(const T &value, const Type &type)

Creates an owned Scalar of a specified type from a scalar value.

Template Parameters:

T – The scalar type to wrap

Parameters:

• type – The Type of the scalar

• value – A scalar value to create a Scalar with

explicit Scalar(std::string_view string)

Creates an owned Scalar from a std::string_view. The value from the original string will be copied.

Parameters:

string – The std::string_view to create a Scalar with

template<typename T>
explicit Scalar(const std::vector<T> &values)

Creates an owned Scalar from a std::vector of scalars. The values in the input vector will be copied.

Parameters:

values – Values to create a Scalar with in a vector.

template<typename T>
explicit Scalar(const tuple<T> &values)

Creates an owned Scalar from a tuple of scalars. The values in the input tuple will be copied.

Parameters:

values – Values to create a Scalar with in a tuple

explicit Scalar(const std::vector<bool> &values)

Creates an owned Scalar from a std::vector<bool>. The values in the input vector will be copied.

Like most things with std::vector<bool>, this construction is not particularly efficient. In order to be copied into the Scalar, the vector will first be “expanded” into a temporary std::vector<std::uint8_t>, resulting in multiple copies being performed.

The user is therefore highly encouraged to use std::vector<std::uint8_t> directly instead of std::vector<bool> (if possible), especially if such vectors are commonly passed to tasks.

Parameters:

values – The values with which to create the Scalar.

template<std::int32_t DIM>
explicit Scalar(

const Point<DIM> &point

)

Creates a point Scalar

Parameters:

point – A Point from which the Scalar should be constructed

template<std::int32_t DIM>
explicit Scalar(const Rect<DIM> &rect)

Creates a Rect Scalar

Parameters:

rect – A Rect from which the Scalar should be constructed

Type type() const

Returns the data type of the Scalar

Returns:

Data Type

std::size_t size() const

Returns the size of allocation for the Scalar.

Returns:

The size of allocation in bytes

template<typename VAL>
VAL value() const

Returns a copy of the value stored in this Scalar.

1) size of the scalar does not match with size of VAL, 2) the scalar holds a string but VAL isn’t std:string or std:string_view, or 3) the inverse; i.e., VAL is std:string or std:string_view but the scalar’s type isn’t string

Template Parameters:

VAL – Type of the value to unwrap

Throws:

std::invalid_argument – If one of the following cases is encountered:

Returns:

A copy of the value stored in this Scalar

template<typename VAL>
Span<const VAL> values() const

Returns values stored in the Scalar. If the Scalar does not have a fixed array type, a unit span will be returned.

1) the scalar has a fixed array type whose element type has a different size from VAL, 2) the scalar holds a string and size of VAL isn’t 1 byte, 3) the scalar’s type isn’t a fixed array type and the size is different from size of VAL

Throws:

std::invalid_argument – If one of the following cases is encountered:

Returns:

Values stored in the Scalar

const void *ptr() const

Returns a raw pointer to the backing allocation.

Returns:

A raw pointer to the Scalar’s data