gko::array< ValueType > Class Template Reference

An array is a container which encapsulates fixed-sized arrays, stored on the Executor tied to the array. More...

#include <ginkgo/core/base/array.hpp>

Inheritance diagram for gko::array< ValueType >:

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 Member Functions
	array () noexcept
	Creates an empty array not tied to any executor. More...
	array (std::shared_ptr< const Executor > exec) noexcept
	Creates an empty array tied to the specified Executor. More...
	array (std::shared_ptr< const Executor > exec, size_type num_elems)
	Creates an array on the specified Executor. More...
template<typename DeleterType >
	array (std::shared_ptr< const Executor > exec, size_type num_elems, value_type *data, DeleterType deleter)
	Creates an array from existing memory. More...
	array (std::shared_ptr< const Executor > exec, size_type num_elems, value_type *data)
	Creates an array from existing memory. More...
template<typename RandomAccessIterator >
	array (std::shared_ptr< const Executor > exec, RandomAccessIterator begin, RandomAccessIterator end)
	Creates an array on the specified Executor and initializes it with values. More...
template<typename T >
	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. More...
	array (std::shared_ptr< const Executor > exec, const array &other)
	Creates a copy of another array on a different executor. More...
	array (const array &other)
	Creates a copy of another array. More...
	array (std::shared_ptr< const Executor > exec, array &&other)
	Moves another array to a different executor. More...
	array (array &&other)
	Moves another array. More...
array< ValueType >	as_view ()
	Returns a non-owning view of the memory owned by this array. More...
detail::const_array_view< ValueType >	as_const_view () const
	Returns a non-owning constant view of the memory owned by this array. More...
array &	operator= (const array &other)
	Copies data from another array or view. More...
array &	operator= (array &&other)
	Moves data from another array or view. More...
template<typename OtherValueType >
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. More...
void	clear () noexcept
	Deallocates all data used by the array. More...
void	resize_and_reset (size_type num_elems)
	Resizes the array so it is able to hold the specified number of elements. More...
void	fill (const value_type value)
	Fill the array with the given value. More...
size_type	get_num_elems () const noexcept
	Returns the number of elements in the array. More...
value_type *	get_data () noexcept
	Returns a pointer to the block of memory used to store the elements of the array. More...
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. More...
std::shared_ptr< const Executor >	get_executor () const noexcept
	Returns the Executor associated with the array. More...
void	set_executor (std::shared_ptr< const Executor > exec)
	Changes the Executor of the array, moving the allocated data to the new Executor. More...
bool	is_owning ()
	Tells whether this array owns its data or not. More...

Static Public Member Functions
static array	view (std::shared_ptr< const Executor > exec, size_type num_elems, value_type *data)
	Creates an array from existing memory. More...
static detail::const_array_view< ValueType >	const_view (std::shared_ptr< const Executor > exec, size_type num_elems, const value_type *data)
	Creates a constant (immutable) array from existing memory. More...

Friends
template<typename OtherValueType >
class	array

Detailed Description

template<typename ValueType>
class gko::array< ValueType >

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

Constructor & Destructor Documentation

array() [1/11]

template<typename ValueType>

gko::array< ValueType >::array ( )

inlinenoexcept

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.

array() [2/11]

template<typename ValueType>

gko::array< ValueType >::array ( std::shared_ptr< const Executor >  exec )

inlineexplicitnoexcept

Creates an empty array tied to the specified Executor.

Parameters

exec	the Executor where the array data is allocated

array() [3/11]

template<typename ValueType>

gko::array< ValueType >::array ( std::shared_ptr< const Executor >  exec, size_type  num_elems  )

inline

Creates an array on the specified Executor.

Parameters

exec	the Executor where the array data will be allocated
num_elems	the amount of memory (expressed as the number of value_type elements) allocated on the Executor

array() [4/11]

template<typename ValueType>

template<typename DeleterType >

gko::array< ValueType >::array ( std::shared_ptr< const Executor >  exec, size_type  num_elems, value_type *  data, DeleterType  deleter  )

inline

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).

Template Parameters

DeleterType

type of the deleter

Parameters

exec	executor where data is located
num_elems	number of elements in data
data	chunk of memory used to create the array
deleter	the deleter used to free the memory

See also

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

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

array() [5/11]

template<typename ValueType>

gko::array< ValueType >::array ( std::shared_ptr< const Executor >  exec, size_type  num_elems, value_type *  data  )

inline

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
num_elems	number of elements in data
data	chunk of memory used to create the array

array() [6/11]

template<typename ValueType>

template<typename RandomAccessIterator >

gko::array< ValueType >::array ( std::shared_ptr< const Executor >  exec, RandomAccessIterator  begin, RandomAccessIterator  end  )

inline

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

array() [7/11]

template<typename ValueType>

template<typename T >

gko::array< ValueType >::array ( std::shared_ptr< const Executor >  exec, std::initializer_list< T >  init_list  )

inline

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

array() [8/11]

template<typename ValueType>

gko::array< ValueType >::array ( std::shared_ptr< const Executor >  exec, const array< ValueType > &  other  )

inline

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

array() [9/11]

template<typename ValueType>

gko::array< ValueType >::array ( const array< ValueType > &  other )

inline

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

array() [10/11]

template<typename ValueType>

gko::array< ValueType >::array ( std::shared_ptr< const Executor >  exec, array< ValueType > &&  other  )

inline

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

array() [11/11]

template<typename ValueType>

gko::array< ValueType >::array ( array< ValueType > &&  other )

inline

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

Member Function Documentation

as_const_view()

template<typename ValueType>

detail::const_array_view<ValueType> gko::array< ValueType >::as_const_view ( ) const

inline

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.

as_view()

template<typename ValueType>

array<ValueType> gko::array< ValueType >::as_view ( )

inline

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.

clear()

template<typename ValueType>

void gko::array< ValueType >::clear ( )

inlinenoexcept

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.

Referenced by gko::index_set< IndexType >::clear(), and gko::array< index_type >::operator=().

const_view()

template<typename ValueType>

static detail::const_array_view<ValueType> gko::array< ValueType >::const_view ( std::shared_ptr< const Executor >  exec, size_type  num_elems, const value_type *  data  )

inlinestatic

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
num_elems	number of elements in data
data	chunk of memory used to create the array

Returns

an array constructed from data

Referenced by gko::array< index_type >::as_const_view().

fill()

template<typename ValueType>

void gko::array< ValueType >::fill

(

const value_type

value

)

Fill the array with the given value.

Parameters

value

the value to be filled

get_const_data()

template<typename ValueType>

const value_type* gko::array< ValueType >::get_const_data ( ) const

inlinenoexcept

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

Referenced by gko::array< index_type >::as_const_view(), gko::batch::matrix::Dense< ValueType >::at(), gko::batch::MultiVector< ValueType >::at(), gko::matrix::Dense< value_type >::at(), gko::preconditioner::Jacobi< ValueType, IndexType >::get_blocks(), gko::preconditioner::Jacobi< ValueType, IndexType >::get_conditioning(), gko::multigrid::Pgm< ValueType, IndexType >::get_const_agg(), gko::batch::matrix::Ell< ValueType, IndexType >::get_const_col_idxs(), gko::matrix::SparsityCsr< ValueType, IndexType >::get_const_col_idxs(), gko::matrix::Sellp< ValueType, IndexType >::get_const_col_idxs(), gko::matrix::Coo< ValueType, IndexType >::get_const_col_idxs(), gko::matrix::Ell< ValueType, IndexType >::get_const_col_idxs(), gko::device_matrix_data< ValueType, IndexType >::get_const_col_idxs(), gko::matrix::Fbcsr< ValueType, IndexType >::get_const_col_idxs(), gko::matrix::Csr< ValueType, IndexType >::get_const_col_idxs(), gko::batch::matrix::Ell< ValueType, IndexType >::get_const_col_idxs_for_item(), gko::matrix::ScaledPermutation< ValueType, IndexType >::get_const_permutation(), gko::matrix::Permutation< IndexType >::get_const_permutation(), gko::matrix::RowGatherer< IndexType >::get_const_row_idxs(), gko::device_matrix_data< ValueType, IndexType >::get_const_row_idxs(), gko::matrix::Coo< ValueType, IndexType >::get_const_row_idxs(), gko::matrix::SparsityCsr< ValueType, IndexType >::get_const_row_ptrs(), gko::matrix::Fbcsr< ValueType, IndexType >::get_const_row_ptrs(), gko::matrix::Csr< ValueType, IndexType >::get_const_row_ptrs(), gko::matrix::ScaledPermutation< ValueType, IndexType >::get_const_scaling_factors(), gko::matrix::Sellp< ValueType, IndexType >::get_const_slice_lengths(), gko::matrix::Sellp< ValueType, IndexType >::get_const_slice_sets(), gko::matrix::Csr< ValueType, IndexType >::get_const_srow(), gko::matrix::SparsityCsr< ValueType, IndexType >::get_const_value(), gko::batch::matrix::Ell< ValueType, IndexType >::get_const_values(), gko::matrix::Diagonal< ValueType >::get_const_values(), gko::batch::matrix::Dense< ValueType >::get_const_values(), gko::matrix::Sellp< ValueType, IndexType >::get_const_values(), gko::matrix::Coo< ValueType, IndexType >::get_const_values(), gko::matrix::Ell< ValueType, IndexType >::get_const_values(), gko::batch::MultiVector< ValueType >::get_const_values(), gko::device_matrix_data< ValueType, IndexType >::get_const_values(), gko::matrix::Fbcsr< ValueType, IndexType >::get_const_values(), gko::matrix::Dense< value_type >::get_const_values(), gko::matrix::Csr< ValueType, IndexType >::get_const_values(), gko::batch::MultiVector< ValueType >::get_const_values_for_item(), gko::batch::matrix::Dense< ValueType >::get_const_values_for_item(), gko::batch::matrix::Ell< ValueType, IndexType >::get_const_values_for_item(), gko::experimental::distributed::Partition< LocalIndexType, GlobalIndexType >::get_part_ids(), gko::experimental::distributed::Partition< LocalIndexType, GlobalIndexType >::get_part_size(), gko::experimental::distributed::Partition< LocalIndexType, GlobalIndexType >::get_part_sizes(), gko::experimental::distributed::Partition< LocalIndexType, GlobalIndexType >::get_range_bounds(), gko::experimental::distributed::Partition< LocalIndexType, GlobalIndexType >::get_range_starting_indices(), gko::index_set< IndexType >::get_subsets_begin(), gko::index_set< IndexType >::get_subsets_end(), gko::index_set< IndexType >::get_superset_indices(), gko::matrix::Csr< ValueType, IndexType >::classical::process(), gko::matrix::Csr< ValueType, IndexType >::load_balance::process(), gko::matrix::Csr< ValueType, IndexType >::automatical::process(), gko::matrix::Ell< ValueType, IndexType >::val_at(), and gko::matrix::Sellp< ValueType, IndexType >::val_at().

get_data()

template<typename ValueType>

value_type* gko::array< ValueType >::get_data ( )

inlinenoexcept

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

Referenced by gko::array< index_type >::as_view(), gko::batch::matrix::Dense< ValueType >::at(), gko::batch::MultiVector< ValueType >::at(), gko::matrix::Dense< value_type >::at(), gko::matrix::Hybrid< ValueType, IndexType >::imbalance_limit::compute_ell_num_stored_elements_per_row(), gko::multigrid::Pgm< ValueType, IndexType >::get_agg(), gko::batch::matrix::Ell< ValueType, IndexType >::get_col_idxs(), gko::matrix::SparsityCsr< ValueType, IndexType >::get_col_idxs(), gko::matrix::Sellp< ValueType, IndexType >::get_col_idxs(), gko::matrix::Coo< ValueType, IndexType >::get_col_idxs(), gko::matrix::Ell< ValueType, IndexType >::get_col_idxs(), gko::device_matrix_data< ValueType, IndexType >::get_col_idxs(), gko::matrix::Fbcsr< ValueType, IndexType >::get_col_idxs(), gko::matrix::Csr< ValueType, IndexType >::get_col_idxs(), gko::batch::matrix::Ell< ValueType, IndexType >::get_col_idxs_for_item(), gko::matrix::ScaledPermutation< ValueType, IndexType >::get_permutation(), gko::matrix::Permutation< IndexType >::get_permutation(), gko::matrix::RowGatherer< IndexType >::get_row_idxs(), gko::matrix::Coo< ValueType, IndexType >::get_row_idxs(), gko::device_matrix_data< ValueType, IndexType >::get_row_idxs(), gko::matrix::SparsityCsr< ValueType, IndexType >::get_row_ptrs(), gko::matrix::Fbcsr< ValueType, IndexType >::get_row_ptrs(), gko::matrix::Csr< ValueType, IndexType >::get_row_ptrs(), gko::matrix::ScaledPermutation< ValueType, IndexType >::get_scaling_factors(), gko::matrix::Sellp< ValueType, IndexType >::get_slice_lengths(), gko::matrix::Sellp< ValueType, IndexType >::get_slice_sets(), gko::matrix::Csr< ValueType, IndexType >::get_srow(), gko::matrix::SparsityCsr< ValueType, IndexType >::get_value(), gko::batch::matrix::Ell< ValueType, IndexType >::get_values(), gko::matrix::Diagonal< ValueType >::get_values(), gko::batch::matrix::Dense< ValueType >::get_values(), gko::matrix::Sellp< ValueType, IndexType >::get_values(), gko::matrix::Coo< ValueType, IndexType >::get_values(), gko::matrix::Ell< ValueType, IndexType >::get_values(), gko::batch::MultiVector< ValueType >::get_values(), gko::device_matrix_data< ValueType, IndexType >::get_values(), gko::matrix::Fbcsr< ValueType, IndexType >::get_values(), gko::matrix::Dense< value_type >::get_values(), gko::matrix::Csr< ValueType, IndexType >::get_values(), gko::batch::MultiVector< ValueType >::get_values_for_item(), gko::batch::matrix::Dense< ValueType >::get_values_for_item(), gko::batch::matrix::Ell< ValueType, IndexType >::get_values_for_item(), gko::array< index_type >::operator=(), gko::matrix::Csr< ValueType, IndexType >::load_balance::process(), gko::matrix::Ell< ValueType, IndexType >::val_at(), and gko::matrix::Sellp< ValueType, IndexType >::val_at().

get_executor()

template<typename ValueType>

std::shared_ptr<const Executor> gko::array< ValueType >::get_executor ( ) const

inlinenoexcept

Returns the Executor associated with the array.

Returns

the Executor associated with the array

Referenced by gko::array< index_type >::as_const_view(), gko::array< index_type >::as_view(), gko::matrix::Hybrid< ValueType, IndexType >::strategy_type::compute_hybrid_config(), gko::device_matrix_data< ValueType, IndexType >::get_executor(), gko::matrix::Csr< ValueType, IndexType >::classical::process(), gko::matrix::Csr< ValueType, IndexType >::load_balance::process(), and gko::matrix::Csr< ValueType, IndexType >::automatical::process().

get_num_elems()

template<typename ValueType>

size_type gko::array< ValueType >::get_num_elems ( ) const

inlinenoexcept

Returns the number of elements in the array.

Returns

the number of elements in the array

Referenced by gko::array< index_type >::as_const_view(), gko::array< index_type >::as_view(), gko::matrix::Hybrid< ValueType, IndexType >::imbalance_limit::compute_ell_num_stored_elements_per_row(), gko::matrix::Hybrid< ValueType, IndexType >::imbalance_bounded_limit::compute_ell_num_stored_elements_per_row(), gko::matrix::Hybrid< ValueType, IndexType >::strategy_type::compute_hybrid_config(), gko::device_matrix_data< ValueType, IndexType >::get_num_elems(), gko::matrix::SparsityCsr< ValueType, IndexType >::get_num_nonzeros(), gko::experimental::distributed::Partition< LocalIndexType, GlobalIndexType >::get_num_ranges(), gko::matrix::Csr< ValueType, IndexType >::get_num_srow_elements(), gko::matrix::Fbcsr< ValueType, IndexType >::get_num_stored_blocks(), gko::batch::matrix::Ell< ValueType, IndexType >::get_num_stored_elements(), gko::matrix::Ell< ValueType, IndexType >::get_num_stored_elements(), gko::matrix::Coo< ValueType, IndexType >::get_num_stored_elements(), gko::batch::MultiVector< ValueType >::get_num_stored_elements(), gko::batch::matrix::Dense< ValueType >::get_num_stored_elements(), gko::matrix::Sellp< ValueType, IndexType >::get_num_stored_elements(), gko::preconditioner::Jacobi< ValueType, IndexType >::get_num_stored_elements(), gko::matrix::Fbcsr< ValueType, IndexType >::get_num_stored_elements(), gko::matrix::Dense< value_type >::get_num_stored_elements(), gko::matrix::Csr< ValueType, IndexType >::get_num_stored_elements(), gko::index_set< IndexType >::get_num_subsets(), gko::matrix::Sellp< ValueType, IndexType >::get_total_cols(), gko::index_set< IndexType >::index_set(), gko::matrix::Csr< ValueType, IndexType >::classical::process(), gko::matrix::Csr< ValueType, IndexType >::load_balance::process(), and gko::matrix::Csr< ValueType, IndexType >::automatical::process().

is_owning()

template<typename ValueType>

bool gko::array< ValueType >::is_owning ( )

inline

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.

Referenced by gko::array< index_type >::operator=().

operator=() [1/3]

template<typename ValueType>

array& gko::array< ValueType >::operator= ( array< ValueType > &&  other )

inline

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

operator=() [2/3]

template<typename ValueType>

array& gko::array< ValueType >::operator= ( const array< ValueType > &  other )

inline

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

operator=() [3/3]

template<typename ValueType>

template<typename OtherValueType >

std::enable_if_t<!std::is_same<ValueType, OtherValueType>::value, array>& gko::array< ValueType >::operator= ( const array< OtherValueType > &  other )

inline

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

resize_and_reset()

template<typename ValueType>

void gko::array< ValueType >::resize_and_reset ( size_type  num_elems )

inline

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

num_elems

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

Referenced by gko::array< index_type >::operator=().

set_executor()

template<typename ValueType>

void gko::array< ValueType >::set_executor ( std::shared_ptr< const Executor >  exec )

inline

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

view()

template<typename ValueType>

static array gko::array< ValueType >::view ( std::shared_ptr< const Executor >  exec, size_type  num_elems, value_type *  data  )

inlinestatic

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
num_elems	number of elements in data
data	chunk of memory used to create the array

Returns

an array constructed from data

Referenced by gko::array< index_type >::as_view().

---

The documentation for this class was generated from the following file:

• ginkgo/core/base/array.hpp