Ginkgo: gko::array< ValueType > Class Template Reference

| Ginkgo Generated from branch based on main. Ginkgo version 1.11.0 A numerical linear algebra library targeting many-core architectures

Loading...
Searching...
No Matches
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 >:
[legend]

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

## Static Public Member Functions
static array | view (std::shared_ptr< const Executor > exec, size_type size, value_type *data)
| Creates an array from existing memory.
static 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.

## 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 | size )
| inline

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

## ◆ array() [4/11]

template<typename ValueType>
template<typename DeleterType>

gko::array< ValueType >::array | ( | std::shared_ptr< const Executor > | exec,
|  | size_type | size,
|  | 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
  size | 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 | size,
|  | 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
  size | 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

References get_executor().

## ◆ 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

References get_executor().

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

References const_view(), get_const_data(), get_executor(), and get_size().

## ◆ 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.

References get_data(), get_executor(), get_size(), and view().

## ◆ 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 operator=(), operator=(), operator=(), operator=(), and resize_and_reset().

## ◆ const_view()

template<typename ValueType>

detail::const_array_view< ValueType > gko::array< ValueType >::const_view | ( | std::shared_ptr< const Executor > | exec,
|  | size_type | size,
|  | 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
  size | number of elements in data
  data | chunk of memory used to create the array

Returns
  an array constructed from data

Referenced by as_const_view(), and gko::make_const_array_view().

## ◆ copy_to_host()

template<typename ValueType>

std::vector< value_type > gko::array< ValueType >::copy_to_host | ( |  | ) | const
| inline

Copies the data into an std::vector.

Returns
  an std::vector containing this array's data.

References get_executor(), get_size(), gko::make_array_view(), and 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 as_const_view(), gko::matrix::Hybrid< ValueType, IndexType >::strategy_type::compute_ell_num_stored_elements_per_row(), operator=(), operator=(), operator=(), gko::matrix::Csr< ValueType, IndexType >::automatical::process(), gko::matrix::Csr< ValueType, IndexType >::classical::process(), and gko::matrix::Csr< ValueType, IndexType >::load_balance::process().

## ◆ 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 as_view(), gko::matrix::Hybrid< ValueType, IndexType >::imbalance_limit::compute_ell_num_stored_elements_per_row(), and gko::matrix::Csr< ValueType, IndexType >::load_balance::process().

## ◆ 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 array(), array(), as_const_view(), as_view(), gko::matrix::Hybrid< ValueType, IndexType >::strategy_type::compute_hybrid_config(), copy_to_host(), operator=(), operator=(), gko::matrix::Csr< ValueType, IndexType >::automatical::process(), gko::matrix::Csr< ValueType, IndexType >::classical::process(), and gko::matrix::Csr< ValueType, IndexType >::load_balance::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

References get_num_elems(), and get_size().

Referenced by get_num_elems().

## ◆ get_size()

template<typename ValueType>

size_type gko::array< ValueType >::get_size | ( |  | ) | const
| inlinenoexcept

Returns the number of elements in the array.

Returns
  the number of elements in the array

Referenced by as_const_view(), as_view(), gko::matrix::Hybrid< ValueType, IndexType >::imbalance_bounded_limit::compute_ell_num_stored_elements_per_row(), gko::matrix::Hybrid< ValueType, IndexType >::imbalance_limit::compute_ell_num_stored_elements_per_row(), gko::matrix::Hybrid< ValueType, IndexType >::strategy_type::compute_ell_num_stored_elements_per_row(), gko::matrix::Hybrid< ValueType, IndexType >::strategy_type::compute_hybrid_config(), copy_to_host(), get_num_elems(), gko::index_set< IndexType >::index_set(), operator=(), operator=(), gko::matrix::Csr< ValueType, IndexType >::automatical::process(), gko::matrix::Csr< ValueType, IndexType >::classical::process(), and gko::matrix::Csr< ValueType, IndexType >::load_balance::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 operator=(), operator=(), operator=(), and resize_and_reset().

## ◆ operator=() [1/4]

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);
gko::array
An array is a container which encapsulates fixed-sized arrays, stored on the Executor tied to the arr...
Definition array.hpp:166

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

References clear().

## ◆ operator=() [2/4]

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

References clear(), get_const_data(), get_executor(), get_size(), is_owning(), and resize_and_reset().

## ◆ operator=() [3/4]

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

References clear(), get_const_data(), get_executor(), get_size(), is_owning(), and resize_and_reset().

## ◆ operator=() [4/4]

template<typename ValueType>

array & gko::array< ValueType >::operator= | ( | const detail::const_array_view< ValueType > & | other | ) |
| inline

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

References clear(), get_const_data(), is_owning(), and resize_and_reset().

## ◆ resize_and_reset()

template<typename ValueType>

void gko::array< ValueType >::resize_and_reset | ( | size_type | size | ) |
| 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

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

References clear(), and is_owning().

Referenced by operator=(), operator=(), and 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>

array gko::array< ValueType >::view | ( | std::shared_ptr< const Executor > | exec,
|  | size_type | size,
|  | 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
  size | number of elements in data
  data | chunk of memory used to create the array

Returns
  an array constructed from data

Referenced by as_view(), copy_to_host(), and gko::make_array_view().

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

- ginkgo/core/base/array.hpp