gko::array#

Owning, executor-aware contiguous buffer of elements of type T. The storage unit that backs every Ginkgo data structure — Csr::values, Dense::values, the row pointers and column indices inside any sparse matrix, the workspace vectors solvers allocate, the stopping-status arrays — is a gko::array<T>.

The class differs from std::vector in two ways that matter for HPC workloads. First, each instance carries a shared_ptr<const Executor>: allocation happens on that executor, and copies between instances transparently dispatch through the executors involved (host-to-device, device-to-device, etc.). Second, gko::array is move-only at the value level — copy construction is forbidden, with explicit clone() / as_view() / as_const_view() helpers covering the cases where a copy or a non-owning view is genuinely wanted. The combination keeps the ownership story explicit and prevents accidental device-side copies when an executor moves through the call chain.

A separate gko::array_view<T> (and its const_array_view<T> counterpart) wraps a borrowed pointer for the case when an Ginkgo data structure should treat application-owned memory as if it were its own, without ever taking ownership.

template<typename ValueType>
class array#

An array is a container which encapsulates fixed-sized arrays, stored on the Executor tied to the array. The array stores and transfers its data as raw memory, which means that the constructors of its elements are not called when constructing, copying or moving the array. Thus, the array class is most suitable for storing POD types.

Template Parameters:

ValueType – the type of elements stored in the array

Public Types

using value_type = ValueType#

The type of elements stored in the array.

using default_deleter = executor_deleter<value_type[]>#

The default deleter type used by array.

using view_deleter = null_deleter<value_type[]>#

The deleter type used for views.

Public Functions

inline array() noexcept#

Creates an empty array not tied to any executor.

An array without an assigned executor can only be empty. Attempts to change its size (e.g. via the resize_and_reset method) will result in an exception. If such an array is used as the right hand side of an assignment or move assignment expression, the data of the target array will be cleared, but its executor will not be modified.

The executor can later be set by using the set_executor method. If an array with no assigned executor is assigned or moved to, it will inherit the executor of the source array.

inline explicit array(
std::shared_ptr<const Executor> exec,
) noexcept#

Creates an empty array tied to the specified Executor.

Parameters:

exec – the Executor where the array data is allocated

inline array(std::shared_ptr<const Executor> exec, size_type size)#

Creates an array on the specified Executor.

Parameters:

  • exec – the Executor where the array data will be allocated

  • size – the amount of memory (expressed as the number of value_type elements) allocated on the Executor

template<typename DeleterType>
inline array(
std::shared_ptr<const Executor> exec,
size_type size,
value_type *data,
DeleterType deleter,
)#

Creates an array from existing memory.

The memory will be managed by the array, and deallocated using the specified deleter (e.g. use std::default_delete for data allocated with new).

See also

array::view() to create an array that does not deallocate memory

See also

array(std::shared_ptr<cont Executor>, size_type, value_type*) to deallocate the memory using Executor::free() method

Template Parameters:

DeleterType – type of the deleter

Parameters:

  • exec – executor where data is located

  • size – number of elements in data

  • data – chunk of memory used to create the array

  • deleter – the deleter used to free the memory

inline array(
std::shared_ptr<const Executor> exec,
size_type size,
value_type *data,
)#

Creates an array from existing memory.

The memory will be managed by the array, and deallocated using the Executor::free method.

Parameters:

  • exec – executor where data is located

  • size – number of elements in data

  • data – chunk of memory used to create the array

template<typename RandomAccessIterator>
inline array(
std::shared_ptr<const Executor> exec,
RandomAccessIterator begin,
RandomAccessIterator end,
)#

Creates an array on the specified Executor and initializes it with values.

Template Parameters:

RandomAccessIterator – type of the iterators

Parameters:

  • exec – the Executor where the array data will be allocated

  • begin – start of range of values

  • end – end of range of values

template<typename T>
inline array(
std::shared_ptr<const Executor> exec,
std::initializer_list<T> init_list,
)#

Creates an array on the specified Executor and initializes it with values.

Template Parameters:

T – type of values used to initialize the array (T has to be implicitly convertible to value_type)

Parameters:

  • exec – the Executor where the array data will be allocated

  • init_list – list of values used to initialize the array

inline array(
std::shared_ptr<const Executor> exec,
const array &other,
)#

Creates a copy of another array on a different executor.

This does not invoke the constructors of the elements, instead they are copied as POD types.

Parameters:

  • exec – the executor where the new array will be created

  • other – the array to copy from

inline array(const array &other)#

Creates a copy of another array.

This does not invoke the constructors of the elements, instead they are copied as POD types.

Parameters:

other – the array to copy from

inline array(std::shared_ptr<const Executor> exec, array &&other)#

Moves another array to a different executor.

This does not invoke the constructors of the elements, instead they are copied as POD types.

Parameters:

  • exec – the executor where the new array will be moved

  • other – the array to move

inline array(array &&other)#

Moves another array.

This does not invoke the constructors of the elements, instead they are copied as POD types.

Parameters:

other – the array to move

inline array<ValueType> as_view()#

Returns a non-owning view of the memory owned by this array. It can only be used until this array gets deleted, cleared or resized.

inline detail::const_array_view<ValueType> as_const_view() const#

Returns a non-owning constant view of the memory owned by this array. It can only be used until this array gets deleted, cleared or resized.

inline array &operator=(const array &other)#

Copies data from another array or view. In the case of an array target, the array is resized to match the source’s size. In the case of a view target, if the dimensions are not compatible a gko::OutOfBoundsError is thrown.

This does not invoke the constructors of the elements, instead they are copied as POD types.

The executor of this is preserved. In case this does not have an assigned executor, it will inherit the executor of other.

Parameters:

other – the array to copy from

Returns:

this

inline array &operator=(array &&other)#

Moves data from another array or view. Only the pointer and deleter type change, a copy only happens when targeting another executor’s data. This means that in the following situation: 

gko::array<int> a; // an existing array or view
gko::array<int> b; // an existing array or view
b = std::move(a);
Depending on whether a and b are array or view, this happens:

  • a and b are views, b becomes the only valid view of a;

  • a and b are arrays, b becomes the only valid array of a;

  • a is a view and b is an array, b frees its data and becomes the only valid view of a ();

  • a is an array and b is a view, b becomes the only valid array of a.

In all the previous cases, a becomes empty (e.g., a nullptr).

This does not invoke the constructors of the elements, instead they are copied as POD types.

The executor of this is preserved. In case this does not have an assigned executor, it will inherit the executor of other.

Parameters:

other – the array to move data from

Returns:

this

template<typename OtherValueType>
inline std::enable_if_t<!std::is_same<ValueType, OtherValueType>::value, array> &operator=(
const array<OtherValueType> &other,
)#

Copies and converts data from another array with another data type. In the case of an array target, the array is resized to match the source’s size. In the case of a view target, if the dimensions are not compatible a gko::OutOfBoundsError is thrown.

This does not invoke the constructors of the elements, instead they are copied as POD types.

The executor of this is preserved. In case this does not have an assigned executor, it will inherit the executor of other.

Parameters:

other – the array to copy from

Template Parameters:

OtherValueType – the value type of other

Returns:

this

inline array &operator=(
const detail::const_array_view<ValueType> &other,
)#

Copies data from a const_array_view.

In the case of an array target, the array is resized to match the source’s size. In the case of a view target, if the dimensions are not compatible a gko::OutOfBoundsError is thrown.

This does not invoke the constructors of the elements, instead they are copied as POD types.

The executor of this is preserved. In case this does not have an assigned executor, it will inherit the executor of other.

Parameters:

other – the const_array_view to copy from

Returns:

this

inline void clear() noexcept#

Deallocates all data used by the array.

The array is left in a valid, but empty state, so the same array can be used to allocate new memory. Calls to array::get_data() will return a nullptr.

inline void resize_and_reset(size_type size)#

Resizes the array so it is able to hold the specified number of elements. For a view and other non-owning array types, this throws an exception since these types cannot be resized.

All data stored in the array will be lost.

If the array is not assigned an executor, an exception will be thrown.

Parameters:

size – the amount of memory (expressed as the number of value_type elements) allocated on the Executor

inline std::vector<value_type> copy_to_host() const#

Copies the data into an std::vector.

Returns:

an std::vector containing this array’s data.

void fill(const value_type value)#

Fill the array with the given value.

Parameters:

value – the value to be filled

inline size_type get_size() const noexcept#

Returns the number of elements in the array.

Returns:

the number of elements in the array

inline size_type get_num_elems() const noexcept#

Returns the number of elements in the array.

Returns:

the number of elements in the array

inline value_type *get_data() noexcept#

Returns a pointer to the block of memory used to store the elements of the array.

Returns:

a pointer to the block of memory used to store the elements of the array

inline const value_type *get_const_data() const noexcept#

Returns a constant pointer to the block of memory used to store the elements of the array.

Returns:

a constant pointer to the block of memory used to store the elements of the array

inline std::shared_ptr<const Executor> get_executor(
) const noexcept#

Returns the Executor associated with the array.

Returns:

the Executor associated with the array

inline void set_executor(std::shared_ptr<const Executor> exec)#

Changes the Executor of the array, moving the allocated data to the new Executor.

Parameters:

exec – the Executor where the data will be moved to

inline bool is_owning()#

Tells whether this array owns its data or not.

Views do not own their data and this has multiple implications. They cannot be resized since the data is not owned by the array which stores a view. It is also unclear whether custom deleter types are owning types as they could be a user-created view-type, therefore only proper array which use the default_deleter are considered owning types.

Returns:

whether this array can be resized or not.

Public Static Functions

static inline array view(
std::shared_ptr<const Executor> exec,
size_type size,
value_type *data,
)#

Creates an array from existing memory.

The array does not take ownership of the memory, and will not deallocate it once it goes out of scope. This array type cannot use the function resize_and_reset since it does not own the data it should resize.

Parameters:

  • exec – executor where data is located

  • size – number of elements in data

  • data – chunk of memory used to create the array

Returns:

an array constructed from data

static inline detail::const_array_view<ValueType> const_view(
std::shared_ptr<const Executor> exec,
size_type size,
const value_type *data,
)#

Creates a constant (immutable) array from existing memory.

The array does not take ownership of the memory, and will not deallocate it once it goes out of scope. This array type cannot use the function resize_and_reset since it does not own the data it should resize.

Parameters:

  • exec – executor where data is located

  • size – number of elements in data

  • data – chunk of memory used to create the array

Returns:

an array constructed from data