Template Numerical Library version\ main:df396df
|
Array is responsible for memory management, access to array elements, and general array operations. More...
#include <TNL/Containers/Array.h>
Public Types | |
using | AllocatorType = Allocator |
Allocator type used for allocating this array. | |
using | ConstViewType = ArrayView< std::add_const_t< Value >, Device, Index > |
Compatible constant ArrayView type. | |
using | DeviceType = Device |
Device used to run operations on the array. | |
using | IndexType = Index |
Type being used for the array elements indexing. | |
template<typename _Value , typename _Device = Device, typename _Index = Index, typename _Allocator = typename Allocators::Default< _Device >::template Allocator< _Value >> | |
using | Self = Array< _Value, _Device, _Index, _Allocator > |
A template which allows to quickly obtain an Array type with changed template parameters. | |
using | ValueType = Value |
Type of elements stored in this array. | |
using | ViewType = ArrayView< Value, Device, Index > |
Compatible ArrayView type. | |
Public Member Functions | |
Array ()=default | |
Constructs an empty array with zero size. | |
Array (Array &&array) noexcept | |
Move constructor for initialization from rvalues. | |
Array (const AllocatorType &allocator) | |
Constructs an empty array and sets the provided allocator. | |
Array (const Array &array) | |
Copy constructor (makes a deep copy). | |
Array (const Array &array, const AllocatorType &allocator) | |
Copy constructor with a specific allocator (makes a deep copy). | |
Array (const Array &array, IndexType begin, IndexType size=0, const AllocatorType &allocator=AllocatorType()) | |
Copy constructor (makes a deep copy). | |
template<typename Value_ , typename Device_ , typename Index_ , typename Allocator_ > | |
Array (const Array< Value_, Device_, Index_, Allocator_ > &a) | |
Copy constructor from array with different template parameters. | |
template<typename InValue > | |
Array (const std::initializer_list< InValue > &list, const AllocatorType &allocator=AllocatorType()) | |
Constructor which initializes the array by copying elements from std::initializer_list, e.g. {...} . | |
template<typename InValue > | |
Array (const std::list< InValue > &list, const AllocatorType &allocator=AllocatorType()) | |
Constructor which initializes the array by copying elements from std::list. | |
template<typename InValue > | |
Array (const std::vector< InValue > &vector, const AllocatorType &allocator=AllocatorType()) | |
Constructor which initializes the array by copying elements from std::vector. | |
Array (IndexType size, const AllocatorType &allocator=AllocatorType()) | |
Constructs an array with given size. | |
Array (IndexType size, ValueType value, const AllocatorType &allocator=AllocatorType()) | |
Constructs an array with given size and value. | |
Array (ValueType *data, IndexType size, const AllocatorType &allocator=AllocatorType()) | |
Constructs an array with given size and copies data from given pointer. | |
virtual | ~Array () |
Destructor. | |
__cuda_callable__ bool | empty () const |
Returns true if the current array size is zero. | |
template<typename Function > | |
void | forAllElements (Function &&f) |
Process the lambda function f for each array element. | |
template<typename Function > | |
void | forAllElements (Function &&f) const |
Process the lambda function f for each array element for constant instances. | |
template<typename Function > | |
void | forElements (IndexType begin, IndexType end, Function &&f) |
Process the lambda function f for each array element in interval [ begin, end). | |
template<typename Function > | |
void | forElements (IndexType begin, IndexType end, Function &&f) const |
Process the lambda function f for each array element in interval [ begin, end) for constant instances of the array. | |
AllocatorType | getAllocator () const |
Returns the allocator associated with the array. | |
__cuda_callable__ Value * | getArrayData () |
Returns a raw pointer to the data. | |
__cuda_callable__ const Value * | getArrayData () const |
Returns a const-qualified raw pointer to the data. | |
ConstViewType | getConstView (IndexType begin=0, IndexType end=0) const |
Returns a non-modifiable view of the array. | |
__cuda_callable__ Value * | getData () |
Returns a raw pointer to the data. | |
__cuda_callable__ const Value * | getData () const |
Returns a const-qualified raw pointer to the data. | |
__cuda_callable__ ValueType | getElement (IndexType i) const |
Returns the value of the i-th element. | |
virtual std::string | getSerializationTypeVirtual () const |
Returns a string representation of the array type in C++ style, with a placeholder in place of Device and Allocator. | |
__cuda_callable__ IndexType | getSize () const |
Returns the current array size. | |
ViewType | getView (IndexType begin=0, IndexType end=0) |
Returns a modifiable view of the array. | |
void | load (const String &fileName) |
Method for loading the array from a binary file fileName. | |
operator ConstViewType () const | |
Conversion operator to a non-modifiable view of the array. | |
operator ViewType () | |
Conversion operator to a modifiable view of the array. | |
template<typename ArrayT > | |
bool | operator!= (const ArrayT &array) const |
Compares the array with another array-like container. | |
__cuda_callable__ Value & | operator() (IndexType i) |
Accesses the i-th element of the array. | |
__cuda_callable__ const Value & | operator() (IndexType i) const |
Accesses the i-th element of the array. | |
Array & | operator= (Array &&array) noexcept(false) |
Move-assignment operator for acquiring data from rvalues. | |
Array & | operator= (const Array &array) |
Copy-assignment operator for copying data from another array. | |
template<typename InValue > | |
Array & | operator= (const std::list< InValue > &list) |
Copies elements from std::list to this array. | |
template<typename InValue > | |
Array< Value, Device, Index, Allocator > & | operator= (const std::list< InValue > &list) |
template<typename InValue > | |
Array & | operator= (const std::vector< InValue > &vector) |
Copies elements from std::vector to this array. | |
template<typename InValue > | |
Array< Value, Device, Index, Allocator > & | operator= (const std::vector< InValue > &vector) |
template<typename T , typename... , typename = std::enable_if_t< std::is_convertible< T, ValueType >::value || IsArrayType< T >::value >> | |
Array & | operator= (const T &data) |
Assigns either array-like container or a single value. | |
template<typename T , typename... , typename > | |
Array< Value, Device, Index, Allocator > & | operator= (const T &data) |
template<typename ArrayT > | |
bool | operator== (const ArrayT &array) const |
Compares the array with another array-like container. | |
__cuda_callable__ Value & | operator[] (IndexType i) |
Accesses the i-th element of the array. | |
__cuda_callable__ const Value & | operator[] (IndexType i) const |
Accesses the i-th element of the array. | |
void | reset () |
Resets the array to the empty state. | |
void | resize (IndexType size) |
Method for resizing the array. | |
void | resize (IndexType size, ValueType value) |
Method for resizing the array with an initial value. | |
void | save (const String &fileName) const |
Method for saving the array to a binary file fileName. | |
__cuda_callable__ void | setElement (IndexType i, ValueType value) |
Sets the value of the i-th element to v. | |
template<typename ArrayT > | |
void | setLike (const ArrayT &array) |
Sets the same size as the size of an existing array. | |
void | setSize (IndexType size) |
Method for setting the array size. | |
void | setValue (ValueType value, IndexType begin=0, IndexType end=0) |
Sets elements of the array to given value. | |
void | swap (Array &array) |
Swaps this array with another. | |
Static Public Member Functions | |
static std::string | getSerializationType () |
Returns a string representation of the array type in C++ style, with a placeholder in place of Device and Allocator. | |
Protected Member Functions | |
void | reallocate (IndexType size) |
Internal method for reallocating array elements. Used only from the two overloads of resize. | |
void | releaseData () |
Internal method for releasing (deallocating) array data. | |
Protected Attributes | |
Allocator | allocator |
The internal allocator instance. | |
Value * | data = nullptr |
Pointer to the data. | |
IndexType | size = 0 |
Number of elements in the array. | |
Array is responsible for memory management, access to array elements, and general array operations.
Value | The type of array elements. |
Device | The device to be used for the execution of array operations. It can be any class defined in the TNL::Devices namespace. |
Index | The indexing type. |
Allocator | The type of the allocator used for the allocation and deallocation of memory used by the array. By default, an appropriate allocator for the specified Device is selected with TNL::Allocators::Default. |
Memory management handled by constructors and destructors according to the RAII principle and by methods resize setSize, setLike, swap, and reset. You can also use methods getSize and empty to check the current array size and getData to access the raw pointer.
Methods annotated as __cuda_callable__ can be called either from host or from kernels executing on a device according to the Device parameter. One of these methods is the operator[] which provides direct access to the array elements. However, it cannot be called from the host if the array was allocated in a memory space which is not directly accessible by the host. If the host needs access to individual array elements which are allocated in a different memory space, they have to be accessed by the setElement or getElement method. However, these methods imply an explicit data transfer which is not buffered, so it can be very slow.
Other methods, such as operator=, operator==, operator!=, and setValue, provide various operations on whole arrays.
See also ArrayView, Vector, VectorView.
using TNL::Containers::Array< Value, Device, Index, Allocator >::AllocatorType = Allocator |
Allocator type used for allocating this array.
See TNL::Allocators.
using TNL::Containers::Array< Value, Device, Index, Allocator >::DeviceType = Device |
Device used to run operations on the array.
See TNL::Devices for the available options.
|
explicit |
Constructs an empty array and sets the provided allocator.
allocator | The allocator to be associated with this array. |
|
explicit |
Constructs an array with given size.
size | The number of array elements to be allocated. |
allocator | The allocator to be associated with this array. |
|
explicit |
Constructs an array with given size and value.
size | The number of array elements to be allocated. |
value | The value all elements will be set to. |
allocator | The allocator to be associated with this array. |
TNL::Containers::Array< Value, Device, Index, Allocator >::Array | ( | ValueType * | data, |
IndexType | size, | ||
const AllocatorType & | allocator = AllocatorType() ) |
Constructs an array with given size and copies data from given pointer.
data | The pointer to the data to be copied to the array. |
size | The number of array elements to be copied to the array. |
allocator | The allocator to be associated with this array. |
|
explicit |
Copy constructor (makes a deep copy).
array | The array to be copied. |
|
explicit |
Copy constructor with a specific allocator (makes a deep copy).
array | The array to be copied. |
allocator | The allocator to be associated with this array. |
TNL::Containers::Array< Value, Device, Index, Allocator >::Array | ( | const Array< Value, Device, Index, Allocator > & | array, |
IndexType | begin, | ||
IndexType | size = 0, | ||
const AllocatorType & | allocator = AllocatorType() ) |
Copy constructor (makes a deep copy).
array | The array to be copied. |
begin | The first index which should be copied. |
size | The number of elements that should be copied. |
allocator | The allocator to be associated with this array. |
|
noexcept |
Move constructor for initialization from rvalues.
array | The array to be moved. |
|
explicit |
Copy constructor from array with different template parameters.
Value_ | Value type of the input array. |
Device_ | Device type of the input array. |
Index_ | Index type of the input array. |
Allocator_ | Allocator type of the input array. |
a | the input array. |
TNL::Containers::Array< Value, Device, Index, Allocator >::Array | ( | const std::initializer_list< InValue > & | list, |
const AllocatorType & | allocator = AllocatorType() ) |
Constructor which initializes the array by copying elements from std::initializer_list, e.g. {...}
.
list | The initializer list containing elements to be copied. |
allocator | The allocator to be associated with this array. |
TNL::Containers::Array< Value, Device, Index, Allocator >::Array | ( | const std::list< InValue > & | list, |
const AllocatorType & | allocator = AllocatorType() ) |
Constructor which initializes the array by copying elements from std::list.
list | The STL list containing elements to be copied. |
allocator | The allocator to be associated with this array. |
TNL::Containers::Array< Value, Device, Index, Allocator >::Array | ( | const std::vector< InValue > & | vector, |
const AllocatorType & | allocator = AllocatorType() ) |
Constructor which initializes the array by copying elements from std::vector.
vector | The STL vector containing elements to be copied. |
allocator | The allocator to be associated with this array. |
|
nodiscard |
Returns true if the current array size is zero.
This method can be called from device kernels.
void TNL::Containers::Array< Value, Device, Index, Allocator >::forAllElements | ( | Function && | f | ) |
Process the lambda function f for each array element.
The lambda function is supposed to be declared as
where
This is performed at the same place where the array is allocated, i.e. it is efficient even on GPU.
f | The lambda function to be processed. |
void TNL::Containers::Array< Value, Device, Index, Allocator >::forAllElements | ( | Function && | f | ) | const |
Process the lambda function f for each array element for constant instances.
The lambda function is supposed to be declared as
where
This is performed at the same place where the array is allocated, i.e. it is efficient even on GPU.
f | The lambda function to be processed. |
void TNL::Containers::Array< Value, Device, Index, Allocator >::forElements | ( | IndexType | begin, |
IndexType | end, | ||
Function && | f ) |
Process the lambda function f for each array element in interval [ begin, end).
The lambda function is supposed to be declared as
where
This is performed at the same place where the array is allocated, i.e. it is efficient even on GPU.
begin | The beginning of the array elements interval. |
end | The end of the array elements interval. |
f | The lambda function to be processed. |
void TNL::Containers::Array< Value, Device, Index, Allocator >::forElements | ( | IndexType | begin, |
IndexType | end, | ||
Function && | f ) const |
Process the lambda function f for each array element in interval [ begin, end) for constant instances of the array.
The lambda function is supposed to be declared as
where
This is performed at the same place where the array is allocated, i.e. it is efficient even on GPU.
begin | The beginning of the array elements interval. |
end | The end of the array elements interval. |
f | The lambda function to be processed. |
|
nodiscard |
Returns a raw pointer to the data.
Use this method in algorithms where you want to emphasize that C-style array pointer is required.
This method can be called from device kernels.
|
nodiscard |
Returns a const-qualified raw pointer to the data.
Use this method in algorithms where you want to emphasize that C-style array pointer is required.
This method can be called from device kernels.
|
nodiscard |
Returns a non-modifiable view of the array.
By default, a view for the whole array is returned. If begin or end is set to a non-zero value, a view only for the sub-interval [begin, end)
is returned.
begin | The beginning of the array sub-interval. It is 0 by default. |
end | The end of the array sub-interval. The default value is 0 which is, however, replaced with the array size. |
|
nodiscard |
Returns a raw pointer to the data.
This method can be called from device kernels.
|
nodiscard |
Returns a const-qualified raw pointer to the data.
This method can be called from device kernels.
|
nodiscard |
Returns the value of the i-th element.
This method can be called from both the host system and the device where the array is allocated.
i | The index of the element to be returned. |
|
nodiscard |
Returns the current array size.
This method can be called from device kernels.
|
nodiscard |
Returns a modifiable view of the array.
By default, a view for the whole array is returned. If begin or end is set to a non-zero value, a view only for the sub-interval [begin, end)
is returned.
begin | The beginning of the array sub-interval. It is 0 by default. |
end | The end of the array sub-interval. The default value is 0 which is, however, replaced with the array size. |
void TNL::Containers::Array< Value, Device, Index, Allocator >::load | ( | const String & | fileName | ) |
Method for loading the array from a binary file fileName.
fileName | The input file name. |
|
nodiscard |
Compares the array with another array-like container.
ArrayT | The type of the parameter can be any array-like container, e.g. Array, ArrayView, Vector, VectorView, etc. |
array | Reference to the array-like container. |
|
nodiscard |
Accesses the i-th element of the array.
Equivalent to operator[], with the same notes and caveats.
|
nodiscard |
Accesses the i-th element of the array.
Equivalent to operator[], with the same notes and caveats.
Array< Value, Device, Index, Allocator > & TNL::Containers::Array< Value, Device, Index, Allocator >::operator= | ( | Array< Value, Device, Index, Allocator > && | array | ) |
Move-assignment operator for acquiring data from rvalues.
array | Reference to the source array. |
Array< Value, Device, Index, Allocator > & TNL::Containers::Array< Value, Device, Index, Allocator >::operator= | ( | const Array< Value, Device, Index, Allocator > & | array | ) |
Copy-assignment operator for copying data from another array.
array | Reference to the source array. |
Array & TNL::Containers::Array< Value, Device, Index, Allocator >::operator= | ( | const std::list< InValue > & | list | ) |
Copies elements from std::list to this array.
list | The STL list containing elements to be copied. |
Array & TNL::Containers::Array< Value, Device, Index, Allocator >::operator= | ( | const std::vector< InValue > & | vector | ) |
Copies elements from std::vector to this array.
vector | The STL vector containing elements to be copied. |
Array & TNL::Containers::Array< Value, Device, Index, Allocator >::operator= | ( | const T & | data | ) |
Assigns either array-like container or a single value.
If T is an array type, e.g. Array, ArrayView, StaticArray, Vector, VectorView, or StaticVector, the elements from data are copied into this array. Otherwise, if it is a type convertible to ValueType, all array elements are set to the value data.
T | The type of the source array or value. |
data | Reference to the source array or value. |
|
nodiscard |
Compares the array with another array-like container.
ArrayT | The type of the parameter can be any array-like container, e.g. Array, ArrayView, Vector, VectorView, etc. |
array | Reference to the array-like container. |
true
if both arrays are element-wise equal and false
otherwise.
|
nodiscard |
Accesses the i-th element of the array.
This method can be called only from the device which has direct access to the memory space where the array was allocated. For example, if the array was allocated in the host memory, it can be called only from host, and if the array was allocated in the device memory, it can be called only from device kernels. If NDEBUG is not defined, assertions inside this methods performs runtime checks for cross-device memory accesses which lead to segmentation fault. If you need to do just a pointer arithmetics use getData instead.
i | The index of the element to be accessed. |
|
nodiscard |
Accesses the i-th element of the array.
This method can be called only from the device which has direct access to the memory space where the array was allocated. For example, if the array was allocated in the host memory, it can be called only from host, and if the array was allocated in the device memory, it can be called only from device kernels. If NDEBUG is not defined, assertions inside this methods performs runtime checks for cross-device memory accesses which lead to segmentation fault. If you need to do just a pointer arithmetics use getData instead.
i | The index of the element to be accessed. |
void TNL::Containers::Array< Value, Device, Index, Allocator >::reset | ( | ) |
Resets the array to the empty state.
The current data will be deallocated, thus all pointers and views to the array elements will become invalid.
void TNL::Containers::Array< Value, Device, Index, Allocator >::resize | ( | IndexType | size | ) |
Method for resizing the array.
The method resizes the array to the given size:
If the array size changes, the current data will be deallocated, thus all pointers and views to the array alements will become invalid.
Note that this method differs from std::vector::resize with respect to the initialization of array elements:
size | The new size of the array. |
void TNL::Containers::Array< Value, Device, Index, Allocator >::resize | ( | IndexType | size, |
ValueType | value ) |
Method for resizing the array with an initial value.
The method resizes the array to the given size:
If the array size changes, the current data will be deallocated, thus all pointers and views to the array alements will become invalid.
size | The new size of the array. |
value | The value to initialize new elements with. |
void TNL::Containers::Array< Value, Device, Index, Allocator >::save | ( | const String & | fileName | ) | const |
Method for saving the array to a binary file fileName.
fileName | The output file name. |
__cuda_callable__ void TNL::Containers::Array< Value, Device, Index, Allocator >::setElement | ( | IndexType | i, |
ValueType | value ) |
Sets the value of the i-th element to v.
This method can be called from both the host system and the device where the array is allocated.
i | The index of the element to be set. |
value | The new value of the element. |
void TNL::Containers::Array< Value, Device, Index, Allocator >::setLike | ( | const ArrayT & | array | ) |
Sets the same size as the size of an existing array.
If the array size changes, the current data will be deallocated, thus all pointers and views to the array alements will become invalid.
Note that this method uses setSize rather than resize.
ArrayT | The type of the parameter can be any type which provides the method getSize() with the same signature as Array. |
array | The array whose size is to be taken. |
void TNL::Containers::Array< Value, Device, Index, Allocator >::setSize | ( | IndexType | size | ) |
Method for setting the array size.
This method behaves almost like resize, but when the array size is changed, old elements are not copied to the new memory location. Hence, this is a shortcut for deallocating the array with resize(0) followed by setting the new size with resize(size)
size | The new size of the array. |
void TNL::Containers::Array< Value, Device, Index, Allocator >::setValue | ( | ValueType | value, |
IndexType | begin = 0, | ||
IndexType | end = 0 ) |
Sets elements of the array to given value.
By default, all array elements are set to the given value. If begin or end is set to a non-zero value, only elements in the sub-interval [begin, end)
are set.
value | The new value for the array elements. |
begin | The beginning of the array sub-interval. It is 0 by default. |
end | The end of the array sub-interval. The default value is 0 which is, however, replaced with the array size. |
void TNL::Containers::Array< Value, Device, Index, Allocator >::swap | ( | Array< Value, Device, Index, Allocator > & | array | ) |
Swaps this array with another.
Swapping is done in a shallow way, i.e. only pointers and sizes are swapped.
array | The array to be swapped with this array. |