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 >:

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.

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

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.

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 >;
   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 __CUDACC__
   std::cout << "The second test runs on GPU ..." << std::endl;
   arrayExample< Devices::Cuda >();
#endif
}

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

allocator

The 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

size	The number of array elements to be allocated.
allocator	The 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

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.

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

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.

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

array

The 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

array	The array to be copied.
allocator	The 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

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.

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

array

The 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

a	the 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

list	The initializer list containing elements to be copied.
allocator	The 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

list	The STL list containing elements to be copied.
allocator	The 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

vector	The STL vector containing elements to be copied.
allocator	The 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 ( ) const

nodiscard

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 )

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

f	The 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 __CUDACC__
   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 ]

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

f	The 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 __CUDACC__
   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

begin	The beginning of the array elements interval.
end	The end of the array elements interval.
f	The 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 __CUDACC__
   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

begin	The beginning of the array elements interval.
end	The end of the array elements interval.
f	The 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 __CUDACC__
   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 ( )

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.

getArrayData() [2/2]

template<typename Value , typename Device , typename Index , typename Allocator >

__cuda_callable__ const Value * TNL::Containers::Array< Value, Device, Index, Allocator >::getArrayData ( ) const

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.

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

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.

Parameters

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.

getData() [1/2]

template<typename Value , typename Device , typename Index , typename Allocator >

__cuda_callable__ Value * TNL::Containers::Array< Value, Device, Index, Allocator >::getData ( )

nodiscard

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 ( ) const

nodiscard

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

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.

Parameters

i	The 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 ( ) const

nodiscard

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 )

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.

Parameters

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.

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

fileName

The 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

nodiscard

Compares the array with another array-like container.

Template Parameters

ArrayT

The type of the parameter can be any array-like container, e.g. Array, ArrayView, Vector, VectorView, etc.

Parameters

array

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

nodiscard

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

nodiscard

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

)

Move-assignment operator for acquiring data from rvalues.

Parameters

array

Reference 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

array

Reference 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

list	The 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

vector

The 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

T	The type of the source array or value.

Parameters

data	Reference 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

nodiscard

Compares the array with another array-like container.

Template Parameters

ArrayT

The type of the parameter can be any array-like container, e.g. Array, ArrayView, Vector, VectorView, etc.

Parameters

array

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

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.

Parameters

i	The 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

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.

Parameters

i	The 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:

• if ValueType is a fundamental type, the elements are default-initialized (i.e., the elements are initialized to indeterminate values).
• otherwise, the elements are value-initialized (like in std::vector::resize).

Parameters

size	The 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

size	The new size of the array.
value	The 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

fileName

The 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

i	The index of the element to be set.
value	The 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

ArrayT

The type of the parameter can be any type which provides the method getSize() with the same signature as Array.

Parameters

array

The 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

size	The 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

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.

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

array

The array to be swapped with this array.

---

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

• src/TNL/Containers/Array.h
• src/TNL/Containers/Array.hpp