This defines the OpenCL version of a device_vector. More...

#include <device_vector.h>

Classes
class	iterator_base
	Base class provided to encapsulate all the common functionality for constant and non-constant iterators. More...

class	reference_base
	A writeable element of the container The location of an element of the container may not actually reside in system memory, but rather in device memory, which may be in a partitioned memory space. Access to a reference of the container results in a mapping and unmapping operation of device memory. More...

class	reverse_iterator_base
	A reverse random access iterator in the classic sense. More...

Public Types
typedef T	value_type

typedef ptrdiff_t	difference_type

typedef difference_type	distance_type

typedef int	size_type

typedef boost::shared_array < value_type >	pointer

typedef boost::shared_array < const value_type >	const_pointer

typedef reference_base < device_vector< value_type > >	reference
	Typedef to create the non-constant reference.

typedef const value_type	const_reference
	A non-writeable copy of an element of the container. Constant references are optimized to return a value_type, since it is certain that the value will not be modified.

typedef iterator_base < device_vector< value_type > >	iterator
	Typedef to create the non-constant iterator.

typedef iterator_base< const device_vector< value_type > >	const_iterator
	Typedef to create the constant iterator.

typedef reverse_iterator_base < device_vector< value_type > >	reverse_iterator
	Typedef to create the non-constant reverse iterator.

typedef reverse_iterator_base < const device_vector < value_type > >	const_reverse_iterator
	Typedef to create the constant reverse iterator.

Public Member Functions
	device_vector (const control &ctl=control::getDefault())
	A default constructor that creates an empty device_vector.

	device_vector (size_type newSize, const value_type &value=value_type(), cl_mem_flags flags=CL_MEM_READ_WRITE, bool init=true, const control &ctl=control::getDefault())
	A constructor that creates a new device_vector with the specified number of elements, with a specified initial value.

template<typename InputIterator >
	device_vector (const InputIterator begin, size_type newSize, cl_mem_flags flags=CL_MEM_READ_WRITE\|CL_MEM_USE_HOST_PTR, bool init=true, const control &ctl=control::getDefault(), typename std::enable_if< !std::is_integral< InputIterator >::value >::type *=0)
	A constructor that creates a new device_vector using a range specified by the user.

template<typename InputIterator >
	device_vector (const InputIterator begin, const InputIterator end, cl_mem_flags flags=CL_MEM_READ_WRITE\|CL_MEM_USE_HOST_PTR, const control &ctl=control::getDefault(), typename std::enable_if< !std::is_integral< InputIterator >::value >::type *=0)
	A constructor that creates a new device_vector using a range specified by the user.

	device_vector (const ::cl::Buffer &rhs, const control &ctl=control::getDefault())
	A constructor that creates a new device_vector using a pre-initialized buffer supplied by the user.

	device_vector (const device_vector &rhs)

device_vector &	operator= (const device_vector &rhs)

void	resize (size_type reqSize, const value_type &val=value_type())
	Change the number of elements in device_vector to reqSize. If the new requested size is less than the original size, the data is truncated and lost. If the new size is greater than the original size, the extra padding will be initialized with the value specified by the user.

size_type	size (void) const
	Return the number of known elements.

size_type	max_size (void) const
	Return the maximum number of elements possible to allocate on the associated device.

void	reserve (size_type reqSize)
	Request a change in the capacity of the device_vector. If reserve completes successfully, this device_vector object guarantees that the it can store the requested amount of elements without another reallocation, until the device_vector size exceeds n.

size_type	capacity (void) const
	Return the maximum possible number of elements without reallocation.

void	shrink_to_fit ()
	Shrink the capacity( ) of this device_vector to just fit its elements. This makes the size( ) of the vector equal to its capacity( ).

reference	operator[] (size_type n)
	Retrieves the value stored at index n.

const_reference	operator[] (size_type n) const
	Retrieves a constant value stored at index n.

iterator	begin (void)
	Retrieves an iterator for this container that points at the beginning element.

const_iterator	begin (void) const
	Retrieves an iterator for this container that points at the beginning constant element. No operation through this iterator may modify the contents of the referenced container.

const_iterator	cbegin (void) const
	Retrieves an iterator for this container that points at the beginning constant element. No operation through this iterator may modify the contents of the referenced container.

reverse_iterator	rbegin (void)
	Retrieves a reverse_iterator for this container that points at the last element.

const_reverse_iterator	rbegin (void) const
	Retrieves a reverse_iterator for this container that points at the last constant element. No operation through this iterator may modify the contents of the referenced container.

const_reverse_iterator	crbegin (void) const
	Retrieves an iterator for this container that points at the last constant element. No operation through this iterator may modify the contents of the referenced container.

iterator	end (void)
	Retrieves an iterator for this container that points at the last element.

const_iterator	end (void) const
	Retrieves an iterator for this container that points at the last constant element. No operation through this iterator may modify the contents of the referenced container.

const_iterator	cend (void) const
	Retrieves an iterator for this container that points at the last constant element. No operation through this iterator may modify the contents of the referenced container.

reverse_iterator	rend (void)
	Retrieves a reverse_iterator for this container that points at the beginning element.

const_reverse_iterator	rend (void) const
	Retrieves a reverse_iterator for this container that points at the beginning constant element. No operation through this iterator may modify the contents of the referenced container.

const_reverse_iterator	crend (void) const
	Retrieves a reverse_iterator for this container that points at the beginning constant element. No operation through this iterator may modify the contents of the referenced container.

reference	front (void)
	Retrieves the value stored at index 0.

const_reference	front (void) const
	Retrieves the value stored at index 0.

reference	back (void)
	Retrieves the value stored at index size( ) - 1.

const_reference	back (void) const
	Retrieves the value stored at index size( ) - 1.

pointer	data (void)

const_pointer	data (void) const

void	clear (void)
	Removes all elements (makes the device_vector empty).

bool	empty (void) const
	Test whether the container is empty.

void	push_back (const value_type &value)
	Appends a copy of the value to the container.

void	pop_back (void)
	Removes the last element, but does not return it.

void	swap (device_vector &vec)
	Swaps the contents of two device_vectors in an efficient manner.

iterator	erase (const_iterator index)
	Removes an element.

iterator	erase (const_iterator first, const_iterator last)
	Removes a range of elements.

iterator	insert (const_iterator index, const value_type &value)
	Insert a new element into the container.

void	insert (const_iterator index, size_type n, const value_type &value)
	Inserts n copies of the new element into the container.

template<typename InputIterator >
void	insert (const_iterator index, InputIterator begin, InputIterator end)

void	assign (size_type newSize, const value_type &value)
	Assigns newSize copies of element value.

template<typename InputIterator >
std::enable_if < !std::is_integral < InputIterator >::value, void > ::type	assign (InputIterator begin, InputIterator end)
	Assigns a range of values to device_vector, replacing all previous elements.

const ::cl::Buffer &	getBuffer () const
	A get accessor function to return the encapsulated device buffer for const objects. This member function allows access to the Buffer object, which can be retrieved through a reference or an iterator. This is necessary to allow library functions to set the encapsulated buffer object as a kernel argument.

::cl::Buffer &	getBuffer ()
	A get accessor function to return the encapsulated device buffer for non-const objects. This member function allows access to the Buffer object, which can be retrieved through a reference or an iterator. This is necessary to allow library functions to set the encapsulated buffer object as a kernel argument.

Detailed Description

template<typename T>
class bolt::cl::device_vector< T >

This defines the OpenCL version of a device_vector.

A device_vector is an abstract data type that provides random access to a flat, sequential region of memory that is performant for the device. This can imply different memories for different devices. For discrete class graphics, devices, this is most likely video memory; for APU devices, this can imply zero-copy memory; for CPU devices, this can imply standard host memory.

See Also: http://www.sgi.com/tech/stl/Vector.html

Member Typedef Documentation

template<typename T>

typedef const value_type bolt::cl::device_vector< T >::const_reference

A non-writeable copy of an element of the container. Constant references are optimized to return a value_type, since it is certain that the value will not be modified.

Note: A const_reference actually returns a value, not a reference.

Constructor & Destructor Documentation

template<typename T>

bolt::cl::device_vector< T >::device_vector ( const control & ctl = control::getDefault( ) )

inline

A default constructor that creates an empty device_vector.

Parameters

ctl	An Bolt control class used to perform copy operations; a default is used if not supplied by the user

Todo:: Find a way to be able to unambiguously specify memory flags for this constructor, that is not confused with the size constructor below.

template<typename T>

bolt::cl::device_vector< T >::device_vector	(	size_type	newSize,
		const value_type &	value = `value_type( )`,
		cl_mem_flags	flags = `CL_MEM_READ_WRITE`,
		bool	init = `true`,
		const control &	ctl = `control::getDefault( )`
	)

inline

A constructor that creates a new device_vector with the specified number of elements, with a specified initial value.

Parameters

newSize	The number of elements of the new device_vector
value	The value with which to initialize new elements.
flags	A bitfield that takes the OpenCL memory flags to help specify where the device_vector allocates memory.
init	Boolean value to indicate whether to initialize device memory from host memory.
ctl	A Bolt control class for copy operations; a default is used if not supplied by the user.

Warning: The ::cl::CommandQueue is not an STD reserve( ) parameter.; If the size of the value is a power of two, the buffer will be filled serially as opposed to using the OpenCL fill API. Refer section 5.2.3 in 'The OpenCL 1.2 Specification' (Khronos)

template<typename T>

template<typename InputIterator >

bolt::cl::device_vector< T >::device_vector	(	const InputIterator	begin,
		size_type	newSize,
		cl_mem_flags	flags = `CL_MEM_READ_WRITE\|CL_MEM_USE_HOST_PTR`,
		bool	init = `true`,
		const control &	ctl = `control::getDefault( )`,
		typename std::enable_if< !std::is_integral< InputIterator >::value >::type *	= `0`
	)

inline

A constructor that creates a new device_vector using a range specified by the user.

Parameters

begin	An iterator pointing at the beginning of the range.
end	An iterator pointing at the end of the range.
flags	A bitfield that takes the OpenCL memory flags to help specify where the device_vector allocates memory.
init	Boolean value to indicate whether to initialize device memory from host memory.
ctl	A Bolt control class used to perform copy operations; a default is used if not supplied by the user.

Note: Ignore the enable_if<> parameter; it prevents this constructor from being called with integral types.

template<typename T>

template<typename InputIterator >

bolt::cl::device_vector< T >::device_vector	(	const InputIterator	begin,
		const InputIterator	end,
		cl_mem_flags	flags = `CL_MEM_READ_WRITE\|CL_MEM_USE_HOST_PTR`,
		const control &	ctl = `control::getDefault( )`,
		typename std::enable_if< !std::is_integral< InputIterator >::value >::type *	= `0`
	)

inline

A constructor that creates a new device_vector using a range specified by the user.

Parameters

begin	An iterator pointing at the beginning of the range.
end	An iterator pointing at the end of the range.
flags	A bitfield that takes the OpenCL memory flags to help specify where the device_vector allocates memory.
ctl	A Bolt control class for copy operations; a default is used if not supplied by the user.

Note: Ignore the enable_if<> parameter; it prevents this constructor from being called with integral types.

template<typename T>

bolt::cl::device_vector< T >::device_vector	(	const ::cl::Buffer &	rhs,
		const control &	ctl = `control::getDefault( )`
	)

inline

A constructor that creates a new device_vector using a pre-initialized buffer supplied by the user.

Parameters

rhs	A pre-existing ::cl::Buffer supplied by the user.
ctl	A Bolt control class for copy operations; a default is used if not supplied by the user.

Member Function Documentation

template<typename T>

void bolt::cl::device_vector< T >::assign	(	size_type	newSize,
		const value_type &	value
	)

inline

Assigns newSize copies of element value.

Parameters

newSize	The new size of the device_vector.
value	The value of the element that is replicated newSize times.

Warning: All previous iterators, references, and pointers are invalidated.; If the size of the value is a power of two, the buffer will be filled serially as opposed to using the OpenCL fill API. Refer section 5.2.3 in 'The OpenCL 1.2 Specification' (Khronos)

template<typename T>

template<typename InputIterator >

std::enable_if< !std::is_integral<InputIterator>::value, void>::type bolt::cl::device_vector< T >::assign	(	InputIterator	begin,
		InputIterator	end
	)

inline

Assigns a range of values to device_vector, replacing all previous elements.

Parameters

begin	The iterator position signifiying the beginning of the range.
end	The iterator position signifying the end of the range (exclusive).

Warning: All previous iterators, references, and pointers are invalidated.

template<typename T>

reference bolt::cl::device_vector< T >::back ( void )

inline

Retrieves the value stored at index size( ) - 1.

Note: This returns a proxy object, to control when device memory gets mapped.

template<typename T>

const_reference bolt::cl::device_vector< T >::back ( void ) const

inline

Retrieves the value stored at index size( ) - 1.

Returns: Returns a const_reference, which is not a proxy object.

template<typename T>

iterator bolt::cl::device_vector< T >::begin ( void )

inline

Retrieves an iterator for this container that points at the beginning element.

Returns: A device_vector< value_type >::iterator.

template<typename T>

const_iterator bolt::cl::device_vector< T >::begin ( void ) const

inline

Retrieves an iterator for this container that points at the beginning constant element. No operation through this iterator may modify the contents of the referenced container.

Returns: A device_vector< value_type >::const_iterator

template<typename T>

size_type bolt::cl::device_vector< T >::capacity ( void ) const

inline

Return the maximum possible number of elements without reallocation.

Note: Capacity() differs from size(), in that capacity() returns the number of elements that could be stored in the memory currently allocated.

Returns: The size of the memory held by device_vector, counted in elements.

template<typename T>

const_iterator bolt::cl::device_vector< T >::cbegin ( void ) const

inline

Retrieves an iterator for this container that points at the beginning constant element. No operation through this iterator may modify the contents of the referenced container.

Note: This method may return a constant iterator from a non-constant container.

Returns: A device_vector< value_type >::const_iterator.

template<typename T>

const_iterator bolt::cl::device_vector< T >::cend ( void ) const

inline

Retrieves an iterator for this container that points at the last constant element. No operation through this iterator may modify the contents of the referenced container.

Note: This method may return a constant iterator from a non-constant container.

Returns: A device_vector< value_type >::const_iterator.

template<typename T>

void bolt::cl::device_vector< T >::clear ( void )

inline

Removes all elements (makes the device_vector empty).

Note: All previous iterators, references and pointers are invalidated.

template<typename T>

const_reverse_iterator bolt::cl::device_vector< T >::crbegin ( void ) const

inline

Retrieves an iterator for this container that points at the last constant element. No operation through this iterator may modify the contents of the referenced container.

Note: This method may return a constant iterator from a non-constant container.

Returns: A device_vector< value_type >::const_reverse_iterator.

template<typename T>

const_reverse_iterator bolt::cl::device_vector< T >::crend ( void ) const

inline

Retrieves a reverse_iterator for this container that points at the beginning constant element. No operation through this iterator may modify the contents of the referenced container.

Note: This method may return a constant iterator from a non-constant container.

Returns: A device_vector< value_type >::const_reverse_iterator.

template<typename T>

bool bolt::cl::device_vector< T >::empty ( void ) const

inline

Test whether the container is empty.

Returns: Returns true if size( ) == 0

template<typename T>

iterator bolt::cl::device_vector< T >::end ( void )

inline

Retrieves an iterator for this container that points at the last element.

Returns: A device_vector< value_type >::iterator.

template<typename T>

const_iterator bolt::cl::device_vector< T >::end ( void ) const

inline

Retrieves an iterator for this container that points at the last constant element. No operation through this iterator may modify the contents of the referenced container.

Returns: A device_vector< value_type >::const_iterator.

template<typename T>

iterator bolt::cl::device_vector< T >::erase ( const_iterator index )

inline

Removes an element.

Parameters

index The iterator position in which to remove the element.

Returns: The iterator position after the deleted element.

template<typename T>

iterator bolt::cl::device_vector< T >::erase	(	const_iterator	first,
		const_iterator	last
	)

inline

Removes a range of elements.

Parameters

begin	The iterator position signifiying the beginning of the range.
end	The iterator position signifying the end of the range (exclusive).

Returns: The iterator position after the deleted range.

template<typename T>

reference bolt::cl::device_vector< T >::front ( void )

inline

Retrieves the value stored at index 0.

Note: This returns a proxy object, to control when device memory gets mapped.

template<typename T>

const_reference bolt::cl::device_vector< T >::front ( void ) const

inline

Retrieves the value stored at index 0.

Returns: Returns a const_reference, which is not a proxy object.

template<typename T>

const ::cl::Buffer& bolt::cl::device_vector< T >::getBuffer ( ) const

inline

A get accessor function to return the encapsulated device buffer for const objects. This member function allows access to the Buffer object, which can be retrieved through a reference or an iterator. This is necessary to allow library functions to set the encapsulated buffer object as a kernel argument.

Note: This get function could be implemented in the iterator, but the reference object is usually a temporary rvalue, so this location seems less intrusive to the design of the vector class.

template<typename T>

::cl::Buffer& bolt::cl::device_vector< T >::getBuffer ( )

inline

A get accessor function to return the encapsulated device buffer for non-const objects. This member function allows access to the Buffer object, which can be retrieved through a reference or an iterator. This is necessary to allow library functions to set the encapsulated buffer object as a kernel argument.

Note: This get function can be implemented in the iterator, but the reference object is usually a temporary rvalue, so this location seems less intrusive to the design of the vector class.

template<typename T>

iterator bolt::cl::device_vector< T >::insert	(	const_iterator	index,
		const value_type &	value
	)

inline

Insert a new element into the container.

Parameters

index	The iterator position to insert a copy of the element.
value	The element to insert.

Returns: The position of the new element.

Note: Only iterators before the insertion point remain valid after the insertion.; If the container must grow to contain the new value, all iterators and references are invalidated.

template<typename T>

void bolt::cl::device_vector< T >::insert	(	const_iterator	index,
		size_type	n,
		const value_type &	value
	)

inline

Inserts n copies of the new element into the container.

Parameters

index	The iterator position to insert n copies of the element.
n	The number of copies of element.
value	The element to insert.

Note: Only iterators before the insertion point remain valid after the insertion.; If the container must grow to contain the new value, all iterators and references are invalidated.

template<typename T>

size_type bolt::cl::device_vector< T >::max_size ( void ) const

inline

Return the maximum number of elements possible to allocate on the associated device.

Returns: The maximum amount of memory possible to allocate, counted in elements.

template<typename T>

reference bolt::cl::device_vector< T >::operator[] ( size_type n )

inline

Retrieves the value stored at index n.

Returns: Returns a proxy reference object, to control when device memory gets mapped.

template<typename T>

const_reference bolt::cl::device_vector< T >::operator[] ( size_type n ) const

inline

Retrieves a constant value stored at index n.

Returns: Returns a const_reference, which is not a proxy object.

template<typename T>

void bolt::cl::device_vector< T >::push_back ( const value_type & value )

inline

Appends a copy of the value to the container.

Parameters

value The element to append

template<typename T>

reverse_iterator bolt::cl::device_vector< T >::rbegin ( void )

inline

Retrieves a reverse_iterator for this container that points at the last element.

Returns: A device_vector< value_type >::reverse_iterator.

template<typename T>

const_reverse_iterator bolt::cl::device_vector< T >::rbegin ( void ) const

inline

Retrieves a reverse_iterator for this container that points at the last constant element. No operation through this iterator may modify the contents of the referenced container.

Returns: A device_vector< value_type >::const_reverse_iterator

template<typename T>

reverse_iterator bolt::cl::device_vector< T >::rend ( void )

inline

Retrieves a reverse_iterator for this container that points at the beginning element.

Returns: A device_vector< value_type >::reverse_iterator.

template<typename T>

const_reverse_iterator bolt::cl::device_vector< T >::rend ( void ) const

inline

Retrieves a reverse_iterator for this container that points at the beginning constant element. No operation through this iterator may modify the contents of the referenced container.

Returns: A device_vector< value_type >::const_reverse_iterator.

template<typename T>

void bolt::cl::device_vector< T >::reserve ( size_type reqSize )

inline

Request a change in the capacity of the device_vector. If reserve completes successfully, this device_vector object guarantees that the it can store the requested amount of elements without another reallocation, until the device_vector size exceeds n.

Parameters

n	The requested size of the device_vector in elements

Note: capacity( ) may exceed n, but will not be less than n.; Contents are preserved, and the size( ) of the vector is not affected.

Warning: if the device_vector must reallocate, all previous iterators, references, and pointers are invalidated.; The ::cl::CommandQueue is not a STD reserve( ) parameter

template<typename T>

void bolt::cl::device_vector< T >::resize	(	size_type	reqSize,
		const value_type &	val = `value_type( )`
	)

inline

Change the number of elements in device_vector to reqSize. If the new requested size is less than the original size, the data is truncated and lost. If the new size is greater than the original size, the extra padding will be initialized with the value specified by the user.

Parameters

reqSize	The requested size of the device_vector in elements.
val	All new elements are initialized with this new value.

Note: capacity( ) may exceed n, but is not less than n.

Warning: If the device_vector must reallocate, all previous iterators, references, and pointers are invalidated.; The ::cl::CommandQueue is not a STD reserve( ) parameter; If the size of the value is a power of two, the buffer will be filled serially as opposed to using the OpenCL fill API. Refer section 5.2.3 in 'The OpenCL 1.2 Specification' (Khronos)

template<typename T>

void bolt::cl::device_vector< T >::shrink_to_fit ( )

inline

Shrink the capacity( ) of this device_vector to just fit its elements. This makes the size( ) of the vector equal to its capacity( ).

Note: Contents are preserved.

Warning: if the device_vector must reallocate, all previous iterators, references, and pointers are invalidated.; The ::cl::CommandQueue is not a STD reserve( ) parameter.

template<typename T>

size_type bolt::cl::device_vector< T >::size ( void ) const

inline

Return the number of known elements.

Note: size( ) differs from capacity( ), in that size( ) returns the number of elements between begin() & end()

Returns: Number of valid elements

template<typename T>

void bolt::cl::device_vector< T >::swap ( device_vector< T > & vec )

inline

Swaps the contents of two device_vectors in an efficient manner.

Parameters

vec	The device_vector to swap with.

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

//bgldinar16/Jenkins_FS_Root/workspace/Bolt_Clone_Local_develop/include/bolt/cl/device_vector.h

Classes

Public Types

Public Member Functions

Detailed Description

template<typename T> class bolt::cl::device_vector< T >

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

template<typename T>
class bolt::cl::device_vector< T >