Template Numerical Library version main:1655e92
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
TNL::Containers::Array< Value, Device, Index, Allocator > Class Template Reference

Array is responsible for memory management, access to array elements, and general array operations. More...

#include <TNL/Containers/Array.h>

Collaboration diagram for TNL::Containers::Array< Value, Device, Index, Allocator >:
Collaboration graph
[legend]

Public Types

using AllocatorType = Allocator
 Allocator type used for allocating this array. More...
 
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. More...
 
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. More...
 
 Array (const AllocatorType &allocator)
 Constructs an empty array and sets the provided allocator. More...
 
 Array (const Array &array)
 Copy constructor (makes a deep copy). More...
 
 Array (const Array &array, const AllocatorType &allocator)
 Copy constructor with a specific allocator (makes a deep copy). More...
 
 Array (const Array &array, IndexType begin, IndexType size=0, const AllocatorType &allocator=AllocatorType())
 Copy constructor (makes a deep copy). More...
 
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. More...
 
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. {...}. More...
 
template<typename InValue >
 Array (const std::list< InValue > &list, const AllocatorType &allocator=AllocatorType())
 Constructor which initializes the array by copying elements from std::list. More...
 
template<typename InValue >
 Array (const std::vector< InValue > &vector, const AllocatorType &allocator=AllocatorType())
 Constructor which initializes the array by copying elements from std::vector. More...
 
 Array (IndexType size, const AllocatorType &allocator=AllocatorType())
 Constructs an array with given size. More...
 
 Array (IndexType size, ValueType value, const AllocatorType &allocator=AllocatorType())
 Constructs an array with given size and value. More...
 
 Array (ValueType *data, IndexType size, const AllocatorType &allocator=AllocatorType())
 Constructs an array with given size and copies data from given pointer. More...
 
virtual ~Array ()
 Destructor.
 
__cuda_callable__ bool empty () const
 Returns true if the current array size is zero. More...
 
template<typename Function >
void forAllElements (Function &&f)
 Process the lambda function f for each array element. More...
 
template<typename Function >
void forAllElements (Function &&f) const
 Process the lambda function f for each array element for constant instances. More...
 
template<typename Function >
void forElements (IndexType begin, IndexType end, Function &&f)
 Process the lambda function f for each array element in interval [ begin, end). More...
 
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. More...
 
AllocatorType getAllocator () const
 Returns the allocator associated with the array.
 
__cuda_callable__ Value * getArrayData ()
 Returns a raw pointer to the data. More...
 
__cuda_callable__ const Value * getArrayData () const
 Returns a const-qualified raw pointer to the data. More...
 
ConstViewType getConstView (IndexType begin=0, IndexType end=0) const
 Returns a non-modifiable view of the array. More...
 
__cuda_callable__ Value * getData ()
 Returns a raw pointer to the data. More...
 
__cuda_callable__ const Value * getData () const
 Returns a const-qualified raw pointer to the data. More...
 
__cuda_callable__ ValueType getElement (IndexType i) const
 Returns the value of the i-th element. More...
 
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. More...
 
ViewType getView (IndexType begin=0, IndexType end=0)
 Returns a modifiable view of the array. More...
 
void load (const String &fileName)
 Method for loading the array from a binary file fileName. More...
 
 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. More...
 
__cuda_callable__ Value & operator() (IndexType i)
 Accesses the i-th element of the array. More...
 
__cuda_callable__ const Value & operator() (IndexType i) const
 Accesses the i-th element of the array. More...
 
Arrayoperator= (Array &&array) noexcept(false)
 Move-assignment operator for acquiring data from rvalues. More...
 
Arrayoperator= (const Array &array)
 Copy-assignment operator for copying data from another array. More...
 
template<typename InValue >
Arrayoperator= (const std::list< InValue > &list)
 Copies elements from std::list to this array. More...
 
template<typename InValue >
Array< Value, Device, Index, Allocator > & operator= (const std::list< InValue > &list)
 
template<typename InValue >
Arrayoperator= (const std::vector< InValue > &vector)
 Copies elements from std::vector to this array. More...
 
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 >>
Arrayoperator= (const T &data)
 Assigns either array-like container or a single value. More...
 
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. More...
 
__cuda_callable__ Value & operator[] (IndexType i)
 Accesses the i-th element of the array. More...
 
__cuda_callable__ const Value & operator[] (IndexType i) const
 Accesses the i-th element of the array. More...
 
void reset ()
 Resets the array to the empty state. More...
 
void resize (IndexType size)
 Method for resizing the array. More...
 
void resize (IndexType size, ValueType value)
 Method for resizing the array with an initial value. More...
 
void save (const String &fileName) const
 Method for saving the array to a binary file fileName. More...
 
__cuda_callable__ void setElement (IndexType i, ValueType value)
 Sets the value of the i-th element to v. More...
 
template<typename ArrayT >
void setLike (const ArrayT &array)
 Sets the same size as the size of an existing array. More...
 
void setSize (IndexType size)
 Method for setting the array size. More...
 
void setValue (ValueType value, IndexType begin=0, IndexType end=0)
 Sets elements of the array to given value. More...
 
void swap (Array &array)
 Swaps this array with another. More...
 

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.
 

Detailed Description

template<typename Value, typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>
class TNL::Containers::Array< Value, Device, Index, Allocator >

Array is responsible for memory management, access to array elements, and general array operations.

Template Parameters
ValueThe type of array elements.
DeviceThe device to be used for the execution of array operations. It can be either Devices::Host or Devices::Cuda.
IndexThe indexing type.
AllocatorThe 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.

Example
#include <iostream>
#include <list>
#include <vector>
#include <TNL/Containers/Array.h>
using namespace TNL;
using namespace std;
/***
* The following works for any device (CPU, GPU ...).
*/
template< typename Device >
void arrayExample()
{
const int size = 10;
using ArrayType = Containers::Array< int, Device >;
using IndexType = typename ArrayType::IndexType;
ArrayType a1( size ), a2( size );
/***
* You may initiate the array using setElement
*/
for( int i = 0; i < size; i++ )
a1.setElement( i, i );
std::cout << "a1 = " << a1 << std::endl;
/***
* You may also assign value to all array elements ...
*/
a2 = 0;
std::cout << "a2 = " << a2 << std::endl;
/***
* ... or assign STL list and vector.
*/
std::list< float > l = { 1.0, 2.0, 3.0 };
std::vector< float > v = { 5.0, 6.0, 7.0 };
a1 = l;
std::cout << "a1 = " << a1 << std::endl;
a1 = v;
std::cout << "a1 = " << a1 << std::endl;
/***
* You may swap array data with the swap method.
*/
a1.swap( a2 );
/***
* You may save it to file and load again
*/
File( "a1.tnl", std::ios_base::out ) << a1;
File( "a1.tnl", std::ios_base::in ) >> a2;
std::remove( "a1.tnl" );
if( a2 != a1 )
std::cerr << "Something is wrong!!!" << std::endl;
std::cout << "a2 = " << a2 << std::endl;
}
int main()
{
std::cout << "The first test runs on CPU ..." << std::endl;
arrayExample< Devices::Host >();
#ifdef HAVE_CUDA
std::cout << "The second test runs on GPU ..." << std::endl;
arrayExample< Devices::Cuda >();
#endif
}
IndexType size
Number of elements in the array.
Definition: Array.h:781
Index IndexType
Type being used for the array elements indexing.
Definition: Array.h:87
T endl(T... args)
The main TNL namespace.
Definition: AtomicOperations.h:13
STL namespace.
T remove(T... args)
Output
The first test runs on CPU ...
a1 = [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
a2 = [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ]
a1 = [ 1, 2, 3 ]
a1 = [ 5, 6, 7 ]
a2 = [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ]
The second test runs on GPU ...
a1 = [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
a2 = [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ]
a1 = [ 1, 2, 3 ]
a1 = [ 5, 6, 7 ]
a2 = [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ]

Member Typedef Documentation

◆ AllocatorType

template<typename Value , typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>
using TNL::Containers::Array< Value, Device, Index, Allocator >::AllocatorType = Allocator

Allocator type used for allocating this array.

See TNL::Allocators.

◆ DeviceType

template<typename Value , typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>
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.

Constructor & Destructor Documentation

◆ Array() [1/12]

template<typename Value , typename Device , typename Index , typename Allocator >
TNL::Containers::Array< Value, Device, Index, Allocator >::Array ( const AllocatorType allocator)
explicit

Constructs an empty array and sets the provided allocator.

Parameters
allocatorThe allocator to be associated with this array.

◆ Array() [2/12]

template<typename Value , typename Device , typename Index , typename Allocator >
TNL::Containers::Array< Value, Device, Index, Allocator >::Array ( IndexType  size,
const AllocatorType allocator = AllocatorType() 
)
explicit

Constructs an array with given size.

Parameters
sizeThe number of array elements to be allocated.
allocatorThe allocator to be associated with this array.

◆ Array() [3/12]

template<typename Value , typename Device , typename Index , typename Allocator >
TNL::Containers::Array< Value, Device, Index, Allocator >::Array ( IndexType  size,
ValueType  value,
const AllocatorType allocator = AllocatorType() 
)
explicit

Constructs an array with given size and value.

Parameters
sizeThe number of array elements to be allocated.
valueThe value all elements will be set to.
allocatorThe allocator to be associated with this array.

◆ Array() [4/12]

template<typename Value , typename Device , typename Index , typename Allocator >
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.

Parameters
dataThe pointer to the data to be copied to the array.
sizeThe number of array elements to be copied to the array.
allocatorThe allocator to be associated with this array.

◆ Array() [5/12]

template<typename Value , typename Device , typename Index , typename Allocator >
TNL::Containers::Array< Value, Device, Index, Allocator >::Array ( const Array< Value, Device, Index, Allocator > &  array)
explicit

Copy constructor (makes a deep copy).

Parameters
arrayThe array to be copied.

◆ Array() [6/12]

template<typename Value , typename Device , typename Index , typename Allocator >
TNL::Containers::Array< Value, Device, Index, Allocator >::Array ( const Array< Value, Device, Index, Allocator > &  array,
const AllocatorType allocator 
)
explicit

Copy constructor with a specific allocator (makes a deep copy).

Parameters
arrayThe array to be copied.
allocatorThe allocator to be associated with this array.

◆ Array() [7/12]

template<typename Value , typename Device , typename Index , typename Allocator >
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).

Parameters
arrayThe array to be copied.
beginThe first index which should be copied.
sizeThe number of elements that should be copied.
allocatorThe allocator to be associated with this array.

◆ Array() [8/12]

template<typename Value , typename Device , typename Index , typename Allocator >
TNL::Containers::Array< Value, Device, Index, Allocator >::Array ( Array< Value, Device, Index, Allocator > &&  array)
noexcept

Move constructor for initialization from rvalues.

Parameters
arrayThe array to be moved.

◆ Array() [9/12]

template<typename Value , typename Device , typename Index , typename Allocator >
template<typename Value_ , typename Device_ , typename Index_ , typename Allocator_ >
TNL::Containers::Array< Value, Device, Index, Allocator >::Array ( const Array< Value_, Device_, Index_, Allocator_ > &  a)
explicit

Copy constructor from array with different template parameters.

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.
Parameters
athe input array.

◆ Array() [10/12]

template<typename Value , typename Device , typename Index , typename Allocator >
template<typename InValue >
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. {...}.

Parameters
listThe initializer list containing elements to be copied.
allocatorThe allocator to be associated with this array.

◆ Array() [11/12]

template<typename Value , typename Device , typename Index , typename Allocator >
template<typename InValue >
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.

Parameters
listThe STL list containing elements to be copied.
allocatorThe allocator to be associated with this array.

◆ Array() [12/12]

template<typename Value , typename Device , typename Index , typename Allocator >
template<typename InValue >
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.

Parameters
vectorThe STL vector containing elements to be copied.
allocatorThe allocator to be associated with this array.

Member Function Documentation

◆ empty()

template<typename Value , typename Device , typename Index , typename Allocator >
bool __cuda_callable__ TNL::Containers::Array< Value, Device, Index, Allocator >::empty

Returns true if the current array size is zero.

This method can be called from device kernels.

◆ forAllElements() [1/2]

template<typename Value , typename Device , typename Index , typename Allocator >
template<typename Function >
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

f( IndexType elementIdx, ValueType& elementValue )
Value ValueType
Type of elements stored in this array.
Definition: Array.h:75

where

  • elementIdx is an index of the array element being currently processed
  • elementValue is a value of the array element being currently processed

This is performed at the same place where the array is allocated, i.e. it is efficient even on GPU.

Parameters
fThe lambda function to be processed.
Example
#include <iostream>
#include <TNL/Containers/Array.h>
#include <TNL/Containers/ArrayView.h>
using namespace TNL;
template< typename Device >
void forElementsExample()
{
/****
* Create new arrays
*/
const int size = 10;
Containers::Array< float, Device > a( size ), b( size );
b = 0;
/****
* Initiate the elements of array `a`
*/
a.forAllElements( [] __cuda_callable__ ( int i, float& value ) { value = i; } );
/****
* Initiate elements of array `b` with indexes 0-4 using `a_view`
*/
auto a_view = a.getView();
b.forElements( 0, 5, [=] __cuda_callable__ ( int i, float& value ) { value = a_view[ i ] + 4.0; } );
/****
* Print the results
*/
std::cout << " a = " << a << std::endl;
std::cout << " b = " << b << std::endl;
}
int main( int argc, char* argv[] )
{
std::cout << "Running example on the host system: " << std::endl;
forElementsExample< Devices::Host >();
#ifdef HAVE_CUDA
std::cout << "Running example on the CUDA device: " << std::endl;
forElementsExample< Devices::Cuda >();
#endif
}
#define __cuda_callable__
Definition: CudaCallable.h:22
Output
Running example on the host system:
a = [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
b = [ 4, 5, 6, 7, 8, 0, 0, 0, 0, 0 ]
Running example on the CUDA device:
a = [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
b = [ 4, 5, 6, 7, 8, 0, 0, 0, 0, 0 ]

◆ forAllElements() [2/2]

template<typename Value , typename Device , typename Index , typename Allocator >
template<typename Function >
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

f( IndexType elementIdx, const ValueType& elementValue )

where

  • elementIdx is an index of the array element being currently processed
  • elementValue is a value of the array element being currently processed

This is performed at the same place where the array is allocated, i.e. it is efficient even on GPU.

Parameters
fThe lambda function to be processed.
Example
#include <iostream>
#include <TNL/Containers/Array.h>
#include <TNL/Containers/ArrayView.h>
using namespace TNL;
template< typename Device >
void forElementsExample()
{
/****
* Create new arrays
*/
const int size = 10;
Containers::Array< float, Device > a( size ), b( size );
b = 0;
/****
* Initiate the elements of array `a`
*/
a.forAllElements( [] __cuda_callable__ ( int i, float& value ) { value = i; } );
/****
* Initiate elements of array `b` with indexes 0-4 using `a_view`
*/
auto a_view = a.getView();
b.forElements( 0, 5, [=] __cuda_callable__ ( int i, float& value ) { value = a_view[ i ] + 4.0; } );
/****
* Print the results
*/
std::cout << " a = " << a << std::endl;
std::cout << " b = " << b << std::endl;
}
int main( int argc, char* argv[] )
{
std::cout << "Running example on the host system: " << std::endl;
forElementsExample< Devices::Host >();
#ifdef HAVE_CUDA
std::cout << "Running example on the CUDA device: " << std::endl;
forElementsExample< Devices::Cuda >();
#endif
}
Output
Running example on the host system:
a = [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
b = [ 4, 5, 6, 7, 8, 0, 0, 0, 0, 0 ]
Running example on the CUDA device:
a = [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
b = [ 4, 5, 6, 7, 8, 0, 0, 0, 0, 0 ]

◆ forElements() [1/2]

template<typename Value , typename Device , typename Index , typename Allocator >
template<typename Function >
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

f( IndexType elementIdx, ValueType& elementValue )

where

  • elementIdx is an index of the array element being currently processed
  • elementValue is a value of the array element being currently processed

This is performed at the same place where the array is allocated, i.e. it is efficient even on GPU.

Parameters
beginThe beginning of the array elements interval.
endThe end of the array elements interval.
fThe lambda function to be processed.
Example
#include <iostream>
#include <TNL/Containers/Array.h>
#include <TNL/Containers/ArrayView.h>
using namespace TNL;
template< typename Device >
void forElementsExample()
{
/****
* Create new arrays
*/
const int size = 10;
Containers::Array< float, Device > a( size ), b( size );
b = 0;
/****
* Initiate the elements of array `a`
*/
a.forAllElements( [] __cuda_callable__ ( int i, float& value ) { value = i; } );
/****
* Initiate elements of array `b` with indexes 0-4 using `a_view`
*/
auto a_view = a.getView();
b.forElements( 0, 5, [=] __cuda_callable__ ( int i, float& value ) { value = a_view[ i ] + 4.0; } );
/****
* Print the results
*/
std::cout << " a = " << a << std::endl;
std::cout << " b = " << b << std::endl;
}
int main( int argc, char* argv[] )
{
std::cout << "Running example on the host system: " << std::endl;
forElementsExample< Devices::Host >();
#ifdef HAVE_CUDA
std::cout << "Running example on the CUDA device: " << std::endl;
forElementsExample< Devices::Cuda >();
#endif
}
Output
Running example on the host system:
a = [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
b = [ 4, 5, 6, 7, 8, 0, 0, 0, 0, 0 ]
Running example on the CUDA device:
a = [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
b = [ 4, 5, 6, 7, 8, 0, 0, 0, 0, 0 ]

◆ forElements() [2/2]

template<typename Value , typename Device , typename Index , typename Allocator >
template<typename Function >
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

f( IndexType elementIdx, const ValueType& elementValue )

where

  • elementIdx is an index of the array element being currently processed
  • elementValue is a value of the array element being currently processed

This is performed at the same place where the array is allocated, i.e. it is efficient even on GPU.

Parameters
beginThe beginning of the array elements interval.
endThe end of the array elements interval.
fThe lambda function to be processed.
Example
#include <iostream>
#include <TNL/Containers/Array.h>
#include <TNL/Containers/ArrayView.h>
using namespace TNL;
template< typename Device >
void forElementsExample()
{
/****
* Create new arrays
*/
const int size = 10;
Containers::Array< float, Device > a( size ), b( size );
b = 0;
/****
* Initiate the elements of array `a`
*/
a.forAllElements( [] __cuda_callable__ ( int i, float& value ) { value = i; } );
/****
* Initiate elements of array `b` with indexes 0-4 using `a_view`
*/
auto a_view = a.getView();
b.forElements( 0, 5, [=] __cuda_callable__ ( int i, float& value ) { value = a_view[ i ] + 4.0; } );
/****
* Print the results
*/
std::cout << " a = " << a << std::endl;
std::cout << " b = " << b << std::endl;
}
int main( int argc, char* argv[] )
{
std::cout << "Running example on the host system: " << std::endl;
forElementsExample< Devices::Host >();
#ifdef HAVE_CUDA
std::cout << "Running example on the CUDA device: " << std::endl;
forElementsExample< Devices::Cuda >();
#endif
}
Output
Running example on the host system:
a = [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
b = [ 4, 5, 6, 7, 8, 0, 0, 0, 0, 0 ]
Running example on the CUDA device:
a = [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
b = [ 4, 5, 6, 7, 8, 0, 0, 0, 0, 0 ]

◆ getArrayData() [1/2]

template<typename Value , typename Device , typename Index , typename Allocator >
__cuda_callable__ Value * TNL::Containers::Array< Value, Device, Index, Allocator >::getArrayData

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.

◆ getArrayData() [2/2]

template<typename Value , typename Device , typename Index , typename Allocator >
__cuda_callable__ const Value * TNL::Containers::Array< Value, Device, Index, Allocator >::getArrayData

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.

◆ getConstView()

template<typename Value , typename Device , typename Index , typename Allocator >
Array< Value, Device, Index, Allocator >::ConstViewType TNL::Containers::Array< Value, Device, Index, Allocator >::getConstView ( IndexType  begin = 0,
IndexType  end = 0 
) const

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.

Parameters
beginThe beginning of the array sub-interval. It is 0 by default.
endThe end of the array sub-interval. The default value is 0 which is, however, replaced with the array size.

◆ getData() [1/2]

template<typename Value , typename Device , typename Index , typename Allocator >
__cuda_callable__ Value * TNL::Containers::Array< Value, Device, Index, Allocator >::getData

Returns a raw pointer to the data.

This method can be called from device kernels.

◆ getData() [2/2]

template<typename Value , typename Device , typename Index , typename Allocator >
__cuda_callable__ const Value * TNL::Containers::Array< Value, Device, Index, Allocator >::getData

Returns a const-qualified raw pointer to the data.

This method can be called from device kernels.

◆ getElement()

template<typename Value , typename Device , typename Index , typename Allocator >
__cuda_callable__ Value TNL::Containers::Array< Value, Device, Index, Allocator >::getElement ( IndexType  i) const

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.

Parameters
iThe index of the element to be returned.

◆ getSize()

template<typename Value , typename Device , typename Index , typename Allocator >
__cuda_callable__ Index TNL::Containers::Array< Value, Device, Index, Allocator >::getSize

Returns the current array size.

This method can be called from device kernels.

◆ getView()

template<typename Value , typename Device , typename Index , typename Allocator >
Array< Value, Device, Index, Allocator >::ViewType TNL::Containers::Array< Value, Device, Index, Allocator >::getView ( IndexType  begin = 0,
IndexType  end = 0 
)

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.

Parameters
beginThe beginning of the array sub-interval. It is 0 by default.
endThe end of the array sub-interval. The default value is 0 which is, however, replaced with the array size.

◆ load()

template<typename Value , typename Device , typename Index , typename Allocator >
void TNL::Containers::Array< Value, Device, Index, Allocator >::load ( const String fileName)

Method for loading the array from a binary file fileName.

Parameters
fileNameThe input file name.

◆ operator!=()

template<typename Value , typename Device , typename Index , typename Allocator >
template<typename ArrayT >
bool TNL::Containers::Array< Value, Device, Index, Allocator >::operator!= ( const ArrayT &  array) const

Compares the array with another array-like container.

Template Parameters
ArrayTThe type of the parameter can be any array-like container, e.g. Array, ArrayView, Vector, VectorView, etc.
Parameters
arrayReference to the array-like container.
Returns
The negated result of operator==.

◆ operator()() [1/2]

template<typename Value , typename Device , typename Index , typename Allocator >
__cuda_callable__ Value & TNL::Containers::Array< Value, Device, Index, Allocator >::operator() ( IndexType  i)

Accesses the i-th element of the array.

Equivalent to operator[], with the same notes and caveats.

◆ operator()() [2/2]

template<typename Value , typename Device , typename Index , typename Allocator >
__cuda_callable__ const Value & TNL::Containers::Array< Value, Device, Index, Allocator >::operator() ( IndexType  i) const

Accesses the i-th element of the array.

Equivalent to operator[], with the same notes and caveats.

◆ operator=() [1/5]

template<typename Value , typename Device , typename Index , typename Allocator >
Array< Value, Device, Index, Allocator > & TNL::Containers::Array< Value, Device, Index, Allocator >::operator= ( Array< Value, Device, Index, Allocator > &&  array)
noexcept

Move-assignment operator for acquiring data from rvalues.

Parameters
arrayReference to the source array.
Returns
Reference to this array.

◆ operator=() [2/5]

template<typename Value , typename Device , typename Index , typename Allocator >
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.

Parameters
arrayReference to the source array.
Returns
Reference to this array.

◆ operator=() [3/5]

template<typename Value , typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>
template<typename InValue >
Array & TNL::Containers::Array< Value, Device, Index, Allocator >::operator= ( const std::list< InValue > &  list)

Copies elements from std::list to this array.

Parameters
listThe STL list containing elements to be copied.
Returns
Reference to this array.

◆ operator=() [4/5]

template<typename Value , typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>
template<typename InValue >
Array & TNL::Containers::Array< Value, Device, Index, Allocator >::operator= ( const std::vector< InValue > &  vector)

Copies elements from std::vector to this array.

Parameters
vectorThe STL vector containing elements to be copied.
Returns
Reference to this array.

◆ operator=() [5/5]

template<typename Value , typename Device = Devices::Host, typename Index = int, typename Allocator = typename Allocators::Default< Device >::template Allocator< Value >>
template<typename T , typename... , typename = std::enable_if_t< std::is_convertible< T, ValueType >::value || IsArrayType< T >::value >>
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.

Template Parameters
TThe type of the source array or value.
Parameters
dataReference to the source array or value.
Returns
Reference to this array.

◆ operator==()

template<typename Value , typename Device , typename Index , typename Allocator >
template<typename ArrayT >
bool TNL::Containers::Array< Value, Device, Index, Allocator >::operator== ( const ArrayT &  array) const

Compares the array with another array-like container.

Template Parameters
ArrayTThe type of the parameter can be any array-like container, e.g. Array, ArrayView, Vector, VectorView, etc.
Parameters
arrayReference to the array-like container.
Returns
true if both arrays are element-wise equal and false otherwise.

◆ operator[]() [1/2]

template<typename Value , typename Device , typename Index , typename Allocator >
__cuda_callable__ Value & TNL::Containers::Array< Value, Device, Index, Allocator >::operator[] ( IndexType  i)

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.

Parameters
iThe index of the element to be accessed.
Returns
Reference to the i-th element.

◆ operator[]() [2/2]

template<typename Value , typename Device , typename Index , typename Allocator >
__cuda_callable__ const Value & TNL::Containers::Array< Value, Device, Index, Allocator >::operator[] ( IndexType  i) const

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.

Parameters
iThe index of the element to be accessed.
Returns
Constant reference to the i-th element.

◆ reset()

template<typename Value , typename Device , typename Index , typename Allocator >
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.

◆ resize() [1/2]

template<typename Value , typename Device , typename Index , typename Allocator >
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 current size is greater than count, the array is reduced to its first size elements.
  • If the current size is less than size, additional elements are appended (see the note below on initialization).
  • If the current size is equal to size, nothing happens.

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:

Parameters
sizeThe new size of the array.

◆ resize() [2/2]

template<typename Value , typename Device , typename Index , typename Allocator >
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 current size is greater than count, the array is reduced to its first size elements.
  • If the current size is less than size, additional copies of value are appended.
  • If the current size is equal to size, nothing happens.

If the array size changes, the current data will be deallocated, thus all pointers and views to the array alements will become invalid.

Parameters
sizeThe new size of the array.
valueThe value to initialize new elements with.

◆ save()

template<typename Value , typename Device , typename Index , typename Allocator >
void TNL::Containers::Array< Value, Device, Index, Allocator >::save ( const String fileName) const

Method for saving the array to a binary file fileName.

Parameters
fileNameThe output file name.

◆ setElement()

template<typename Value , typename Device , typename Index , typename Allocator >
__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.

Parameters
iThe index of the element to be set.
valueThe new value of the element.

◆ setLike()

template<typename Value , typename Device , typename Index , typename Allocator >
template<typename ArrayT >
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.

Template Parameters
ArrayTThe type of the parameter can be any type which provides the method getSize() with the same signature as Array.
Parameters
arrayThe array whose size is to be taken.

◆ setSize()

template<typename Value , typename Device , typename Index , typename Allocator >
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)

Parameters
sizeThe new size of the array.

◆ setValue()

template<typename Value , typename Device , typename Index , typename Allocator >
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.

Parameters
valueThe new value for the array elements.
beginThe beginning of the array sub-interval. It is 0 by default.
endThe end of the array sub-interval. The default value is 0 which is, however, replaced with the array size.

◆ swap()

template<typename Value , typename Device , typename Index , typename Allocator >
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.

Parameters
arrayThe array to be swapped with this array.

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