SkelCL
SkelCL is a high level multi GPU skeleton library developed at the university of Münster, Germany.
|
The Vector class is a one dimensional container which makes its data accessible on the host as well as on the devices. More...
#include <Vector.h>
Public Types | |
typedef std::vector< T > | host_buffer_type |
The type used to store the elements on the host. | |
typedef host_buffer_type::value_type | value_type |
The type of the elements. | |
typedef host_buffer_type::pointer | pointer |
The type of a pointer to an element. | |
typedef host_buffer_type::const_pointer | const_pointer |
The type of a const pointer to an element. | |
typedef host_buffer_type::reference | reference |
The type of a reference to an element. | |
typedef host_buffer_type::const_reference | const_reference |
The type of a const reference to an element. | |
typedef host_buffer_type::iterator | iterator |
The type of an iterator. | |
typedef host_buffer_type::const_iterator | const_iterator |
The type of an const iterator. | |
typedef host_buffer_type::reverse_iterator | reverse_iterator |
The type of a reverse iterator. | |
typedef host_buffer_type::const_reverse_iterator | const_reverse_iterator |
The type of a const reverse iterator. | |
typedef host_buffer_type::size_type | size_type |
The integral type used to define the number of the elements in the Vector. | |
typedef host_buffer_type::difference_type | difference_type |
The integral type used to define differences of two size_type values. | |
typedef host_buffer_type::allocator_type | allocator_type |
The type of the allocator used on the host. | |
Public Member Functions | |
Vector () | |
Creates a new empty Vector. | |
Vector (const size_type size, const value_type &value=value_type(), const detail::Distribution< Vector< T >> &distribution=detail::Distribution< Vector< T >>()) | |
Creates a new Vector with size many elements. More... | |
template<class InputIterator > | |
Vector (InputIterator first, InputIterator last) | |
Creates a new Vector with the content of the range [first, last) . More... | |
template<class InputIterator > | |
Vector (InputIterator first, InputIterator last, const detail::Distribution< Vector< T >> &distribution) | |
Creates a new Vector with the content of the range [first, last) . More... | |
Vector (const Vector< T > &rhs) | |
Copy constructor. Creates a new Vector with the copy of the content of rhs . More... | |
Vector (Vector< T > &&rhs) | |
Move constructor. Creates a new Vector by moving the content of rhs . More... | |
Vector< T > & | operator= (const Vector< T > &rhs) |
Copy assignment operator. Replaces the content with a copy of the content of rhs . More... | |
Vector< T > & | operator= (Vector< T > &&rhs) |
Move assignment operator. Replaces the content by moving the content of rhs . More... | |
~Vector () | |
Destructs the Vector. More... | |
iterator | begin () |
Returns an iterator to the first element of the Vector. More... | |
const_iterator | begin () const |
Returns a constant iterator to the first element of the Vector. More... | |
iterator | end () |
Returns an iterator to the element following the last element of the Vector. More... | |
const_iterator | end () const |
Returns a constant iterator to the element following the last element of the Vector. More... | |
size_type | size () const |
Returns the number of elements in the Vector. More... | |
detail::Sizes | sizes () const |
Returns the number of elements stored on each device. More... | |
size_type | max_size () const |
Return the maximum number of elements the Vector is able to hold. More... | |
void | resize (size_type count, T value=T()) |
Resizes the container to contain count elements. More... | |
size_type | capacity () const |
Returns the number of elements that the Vector has currently allocated space for. More... | |
bool | empty () const |
Checks if the Vector has no elements, i.e. whether begin() == end() More... | |
void | reserve (size_type n) |
Increases the capacity of the Vector to a value that's greater or equal to n . More... | |
reference | operator[] (size_type pos) |
Returns a reference to the element at the specified location pos . No boundary checks are performed. More... | |
const_reference | operator[] (size_type pos) const |
Returns a constant reference to the element at the specified location pos . No boundary checks are performed. More... | |
reference | at (size_type pos) |
Returns a reference to the element at the specified location pos . Boundary checks are performed. More... | |
const_reference | at (size_type pos) const |
Returns a constant reference to the element at the specified location pos . Boundary checks are performed. More... | |
reference | front () |
Returns a reference to the first element in the Vector. Calling front() on an empty Vector is undefined. More... | |
const_reference | front () const |
Returns a constant reference to the first element in the Vector. Calling front() on an empty Vector is undefined. More... | |
reference | back () |
Returns a reference to the last element in the Vector. Calling back() on an empty Vector is undefined. More... | |
const_reference | back () const |
Returns a constant reference to the last element in the Vector. Calling back() on an empty Vector is undefined. More... | |
template<class InputIterator > | |
void | assign (InputIterator first, InputIterator last) |
Replaces the contents of the Vector with copies of the elements in the range [first, last) . More... | |
void | assign (size_type count, const T &value) |
Replaces the contents of the Vector with count copies of value . More... | |
void | push_back (const T &value) |
Appends a copy of the given element value to the end of the Vector. More... | |
void | pop_back () |
Removes the last element of the Vector. More... | |
iterator | insert (iterator pos, const T &value) |
Inserts copy of value at the specified location in the Vector. More... | |
iterator | insert (iterator pos, size_type count, const T &value) |
Inserts count copy of value at the specified location in the Vector. More... | |
template<class InputIterator > | |
void | insert (iterator pos, InputIterator first, InputIterator last) |
Inserts elements from range [first, last) at the specified location in the Vector. More... | |
iterator | erase (iterator pos) |
Remove the specified element from the Vector. More... | |
iterator | erase (iterator first, iterator last) |
Remove the specified element in the range [first, last) from the Vector. More... | |
void | swap (Vector< T > &rhs) |
Exchanges the contents of the Vectors with those of rhs . More... | |
void | clear () |
Removes all elements from the Vector. More... | |
detail::Distribution< Vector < T > > & | distribution () const |
Returns the current distribution of the vector. More... | |
template<typename U > | |
void | setDistribution (const detail::Distribution< Vector< U >> &distribution) const |
Set a new distribution to the vector. More... | |
template<typename U > | |
void | setDistribution (const std::unique_ptr< detail::Distribution< Vector< U >>> &distribution) const |
Set a new distribution to the vector. More... | |
void | setDistribution (std::unique_ptr< detail::Distribution< Vector< T >>> &&distribution) const |
Set a new distribution to the vector. More... | |
void | createDeviceBuffers () const |
Create buffers on the devices involved in the current distribution. More... | |
void | forceCreateDeviceBuffers () const |
Forces the creation of buffers on the devices involved in the current distribution, even if this means replacing existing buffers. More... | |
detail::Event | startUpload () const |
Starts copying data from the host to the devices involved in the current distribution. More... | |
void | copyDataToDevices () const |
Copies data from the host to the devices involved in the current distribution. More... | |
detail::Event | startDownload () const |
Starts copying data from the devices involved in the current distribution to the host. More... | |
void | copyDataToHost () const |
Copies data from the devices involved in the current distribution to the host. More... | |
void | dataOnDeviceModified () const |
Marks the data on the device as been modified. More... | |
void | dataOnHostModified () const |
Marks the data on the host as been modified. More... | |
bool | hostIsUpToDate () const |
Returns if the elements stored on the host are up to date, or if the elements are outdated because the elements on the devices have been modified more recently. More... | |
bool | devicesAreUpToDate () const |
Returns if the elements stored on the devices are up to date, or if the elements are outdated because the elements on the host have been modified more recently. More... | |
const detail::DeviceBuffer & | deviceBuffer (const detail::Device &device) const |
Returns the buffer for the given device used to store elements of the vector accordingly to the current distribution. More... | |
detail::DeviceBuffer & | deviceBuffer (const detail::Device &device) |
Returns a reference to the underlying object storing the elements on the given device. More... | |
host_buffer_type & | hostBuffer () const |
Returns a reference to the underlying object storing the elements on the host. More... | |
Static Public Member Functions | |
static std::string | deviceFunctions () |
Returns the source code of helper functions simplifying access to the vector on the device. More... | |
The Vector class is a one dimensional container which makes its data accessible on the host as well as on the devices.
The interface resembles the interface of the std::vector. Access to elements is possible by calling member functions or using iterators.
Different to the std::vector are the possibility to set a Distribution, which explains how the elements should be distributed across multiple devices. In addition, there exist functions to copy the element to and from the devices and to access the underlying OpenCL objects.
skelcl::Vector< T >::Vector | ( | const size_type | size, |
const value_type & | value = value_type() , |
||
const detail::Distribution< Vector< T >> & | distribution = detail::Distribution< Vector< T >>() |
||
) |
skelcl::Vector< T >::Vector | ( | InputIterator | first, |
InputIterator | last | ||
) |
Creates a new Vector with the content of the range [first, last)
.
Complexity Linear in distance between first
and last
first | Begin of the range to copy the elements from |
last | End of the range to copy the elements from |
skelcl::Vector< T >::Vector | ( | InputIterator | first, |
InputIterator | last, | ||
const detail::Distribution< Vector< T >> & | distribution | ||
) |
skelcl::Vector< T >::Vector | ( | const Vector< T > & | rhs | ) |
skelcl::Vector< T >::Vector | ( | Vector< T > && | rhs | ) |
skelcl::Vector< T >::~Vector | ( | ) |
void skelcl::Vector< T >::assign | ( | InputIterator | first, |
InputIterator | last | ||
) |
Replaces the contents of the Vector with copies of the elements in the range [first, last)
.
Complexity Linear in distance between first
and last
first | Begin of the range to copy the elements from |
last | End of the range to copy the elements from |
void skelcl::Vector< T >::assign | ( | size_type | count, |
const T & | value | ||
) |
reference skelcl::Vector< T >::at | ( | size_type | pos | ) |
Returns a reference to the element at the specified location pos
. Boundary checks are performed.
If pos
is not within the range of the Vector, an exception of the type std::out_of_range is thrown.
If the data on the host is not up to date this function will block until the elements of the Vector are transfered from the devices to the host.
Complexity Constant if hostIsUpToDate() returns true
. Linear in size of the Vector otherwise.
pos | Position of the element to access |
const_reference skelcl::Vector< T >::at | ( | size_type | pos | ) | const |
Returns a constant reference to the element at the specified location pos
. Boundary checks are performed.
If pos
is not within the range of the Vector, an exception of the type std::out_of_range is thrown.
If the data on the host is not up to date this function will block until the elements of the Vector are transfered from the devices to the host.
Complexity Constant if hostIsUpToDate() returns true
. Linear in size of the Vector otherwise.
pos | Position of the element to access |
reference skelcl::Vector< T >::back | ( | ) |
Returns a reference to the last element in the Vector. Calling back() on an empty Vector is undefined.
If the data on the host is not up to date this function will block until the elements of the Vector are transfered from the devices to the host.
Complexity Constant if hostIsUpToDate() returns true
. Linear in size of the Vector otherwise.
const_reference skelcl::Vector< T >::back | ( | ) | const |
Returns a constant reference to the last element in the Vector. Calling back() on an empty Vector is undefined.
If the data on the host is not up to date this function will block until the elements of the Vector are transfered from the devices to the host.
Complexity Constant if hostIsUpToDate() returns true
. Linear in size of the Vector otherwise.
iterator skelcl::Vector< T >::begin | ( | ) |
Returns an iterator to the first element of the Vector.
If the data on the host is not up to date this function will block until the elements of the Vector are transfered from the devices to the host.
If the container is empty, the returned iterator will be equal to end().
Complexity Constant if hostIsUpToDate() returns true
. Linear in size of the Vector otherwise.
const_iterator skelcl::Vector< T >::begin | ( | ) | const |
Returns a constant iterator to the first element of the Vector.
If the data on the host is not up to date this function will block until the elements of the Vector are transfered from the devices to the host.
If the container is empty, the returned iterator will be equal to end().
Complexity Constant if hostIsUpToDate() returns true
. Linear in size of the Vector otherwise.
size_type skelcl::Vector< T >::capacity | ( | ) | const |
Returns the number of elements that the Vector has currently allocated space for.
Complexity Constant
void skelcl::Vector< T >::clear | ( | ) |
void skelcl::Vector< T >::copyDataToDevices | ( | ) | const |
Copies data from the host to the devices involved in the current distribution.
This function blocks until the copy operation is finished. For an unblocking version use startUpload().
Complexity Linear in the size of the vector.
void skelcl::Vector< T >::copyDataToHost | ( | ) | const |
Copies data from the devices involved in the current distribution to the host.
This function blocks until the copy operation is finished. For an unblocking version use startDownload().
Complexity Linear in the size of the vector.
void skelcl::Vector< T >::createDeviceBuffers | ( | ) | const |
Create buffers on the devices involved in the current distribution.
This function is a no-op if the buffers are already created. If you want to force the creation, e.g. replace existing buffers, use forceCreateDeviceBuffers()
Complexity Linear in the number of device (usually small)
void skelcl::Vector< T >::dataOnDeviceModified | ( | ) | const |
Marks the data on the device as been modified.
Complexity Constant
void skelcl::Vector< T >::dataOnHostModified | ( | ) | const |
Marks the data on the host as been modified.
Complexity Constant
const detail::DeviceBuffer& skelcl::Vector< T >::deviceBuffer | ( | const detail::Device & | device | ) | const |
Returns the buffer for the given device used to store elements of the vector accordingly to the current distribution.
device | The device for which the buffer should be returned. The device must be part of the current distribution and the device buffers have to be already created, otherwise the behavior is undefined. |
detail::DeviceBuffer& skelcl::Vector< T >::deviceBuffer | ( | const detail::Device & | device | ) |
Returns a reference to the underlying object storing the elements on the given device.
Complexity Constant
device | The device for which the storage object should be returned |
|
static |
Returns the source code of helper functions simplifying access to the vector on the device.
Complexity Constant
bool skelcl::Vector< T >::devicesAreUpToDate | ( | ) | const |
Returns if the elements stored on the devices are up to date, or if the elements are outdated because the elements on the host have been modified more recently.
Complexity Constant
detail::Distribution<Vector<T> >& skelcl::Vector< T >::distribution | ( | ) | const |
Returns the current distribution of the vector.
Complexity Constant
bool skelcl::Vector< T >::empty | ( | ) | const |
iterator skelcl::Vector< T >::end | ( | ) |
Returns an iterator to the element following the last element of the Vector.
If the data on the host is not up to date this function will block until the elements of the Vector are transfered from the devices to the host.
Complexity Constant if hostIsUpToDate() returns true
. Linear in size of the Vector otherwise.
const_iterator skelcl::Vector< T >::end | ( | ) | const |
Returns a constant iterator to the element following the last element of the Vector.
If the data on the host is not up to date this function will block until the elements of the Vector are transfered from the devices to the host.
Complexity Constant if hostIsUpToDate() returns true
. Linear in size of the Vector otherwise.
iterator skelcl::Vector< T >::erase | ( | iterator | pos | ) |
iterator skelcl::Vector< T >::erase | ( | iterator | first, |
iterator | last | ||
) |
void skelcl::Vector< T >::forceCreateDeviceBuffers | ( | ) | const |
Forces the creation of buffers on the devices involved in the current distribution, even if this means replacing existing buffers.
If you want to create the buffers only if no buffers are already created use createDeviceBuffers()
Complexity Linear in the number of devices (usually small)
reference skelcl::Vector< T >::front | ( | ) |
Returns a reference to the first element in the Vector. Calling front() on an empty Vector is undefined.
If the data on the host is not up to date this function will block until the elements of the Vector are transfered from the devices to the host.
Complexity Constant if hostIsUpToDate() returns true
. Linear in size of the Vector otherwise.
const_reference skelcl::Vector< T >::front | ( | ) | const |
Returns a constant reference to the first element in the Vector. Calling front() on an empty Vector is undefined.
If the data on the host is not up to date this function will block until the elements of the Vector are transfered from the devices to the host.
Complexity Constant if hostIsUpToDate() returns true
. Linear in size of the Vector otherwise.
host_buffer_type& skelcl::Vector< T >::hostBuffer | ( | ) | const |
Returns a reference to the underlying object storing the elements on the host.
Complexity Constant
bool skelcl::Vector< T >::hostIsUpToDate | ( | ) | const |
Returns if the elements stored on the host are up to date, or if the elements are outdated because the elements on the devices have been modified more recently.
Complexity Constant
iterator skelcl::Vector< T >::insert | ( | iterator | pos, |
const T & | value | ||
) |
Inserts copy of value
at the specified location in the Vector.
Complexity Constant plus linear in the distance between pos
and end of the Vector
pos | Iterator to the location before which the copy of value will be inserted. pos may be the end() iterator. |
value | Element value to insert |
iterator skelcl::Vector< T >::insert | ( | iterator | pos, |
size_type | count, | ||
const T & | value | ||
) |
Inserts count
copy of value
at the specified location in the Vector.
Complexity Linear in count
plus linear in the distance between pos
and end of the Vector
pos | Iterator to the location before which the copy of value will be inserted. pos may be the end() iterator |
count | How many times value should be inserted into the Vector |
value | Element value to insert |
void skelcl::Vector< T >::insert | ( | iterator | pos, |
InputIterator | first, | ||
InputIterator | last | ||
) |
Inserts elements from range [first, last)
at the specified location in the Vector.
Complexity Linear in std::distance(first, last)
plus linear in the distance between pos
and end of the Vector
pos | Iterator to the location before which the elements will be inserted. pos may be the end() iterator |
first | Start of the range of elements to be inserted |
last | End of the range of elements to be inserted |
size_type skelcl::Vector< T >::max_size | ( | ) | const |
Return the maximum number of elements the Vector is able to hold.
Complexity Constant
Vector<T>& skelcl::Vector< T >::operator= | ( | const Vector< T > & | rhs | ) |
Vector<T>& skelcl::Vector< T >::operator= | ( | Vector< T > && | rhs | ) |
reference skelcl::Vector< T >::operator[] | ( | size_type | pos | ) |
Returns a reference to the element at the specified location pos
. No boundary checks are performed.
If the data on the host is not up to date this function will block until the elements of the Vector are transfered from the devices to the host.
Complexity Constant if hostIsUpToDate() returns true
. Linear in size of the Vector otherwise.
pos | Position of the element to access |
const_reference skelcl::Vector< T >::operator[] | ( | size_type | pos | ) | const |
Returns a constant reference to the element at the specified location pos
. No boundary checks are performed.
If the data on the host is not up to date this function will block until the elements of the Vector are transfered from the devices to the host.
Complexity Constant if hostIsUpToDate() returns true
. Linear in size of the Vector otherwise.
pos | Position of the element to access |
void skelcl::Vector< T >::pop_back | ( | ) |
void skelcl::Vector< T >::push_back | ( | const T & | value | ) |
Appends a copy of the given element value to the end of the Vector.
Complexity Amortized constant.
value | The value of the element to append |
void skelcl::Vector< T >::reserve | ( | size_type | n | ) |
Increases the capacity of the Vector to a value that's greater or equal to n
.
If n
is greater than current capacity(), new storage is allocated, otherwise the function does nothing. If is
greater than capacity(), all iterators and references are invalidated. Otherwise, no iterators or references are invalidated.
Complexity At most linear in the size() of the Vector
n | New capacity of the Vector |
void skelcl::Vector< T >::resize | ( | size_type | count, |
T | value = T() |
||
) |
Resizes the container to contain count
elements.
If the current size is greater than count
, the Vector is reduced to its first count
elements as if by repeatedly calling pop_back()
Complexity Linear in the size of the Vector
count | New size of the Vector |
value | The value to initialize the new elements with |
void skelcl::Vector< T >::setDistribution | ( | const detail::Distribution< Vector< U >> & | distribution | ) | const |
Set a new distribution to the vector.
Changing the distribution might lead to data transfer between the host and the devices later on.
Complexity Constant
distribution | The new distribution to be set. After this call distribution is the new selected distribution of the vector |
void skelcl::Vector< T >::setDistribution | ( | const std::unique_ptr< detail::Distribution< Vector< U >>> & | distribution | ) | const |
Set a new distribution to the vector.
Changing the distribution might lead to data transfer between the host and the devices later on.
Complexity Constant
distribution | The new distribution to be set. After this call distribution is the new selected distribution of the vector |
void skelcl::Vector< T >::setDistribution | ( | std::unique_ptr< detail::Distribution< Vector< T >>> && | distribution | ) | const |
Set a new distribution to the vector.
Changing the distribution might lead to data transfer between the host and the devices later on.
Complexity Constant
distribution | The new distribution to be set. After this call distribution is the new selected distribution of the vector |
size_type skelcl::Vector< T >::size | ( | ) | const |
detail::Sizes skelcl::Vector< T >::sizes | ( | ) | const |
Returns the number of elements stored on each device.
Complexity Linear in number of devices (usually small)
detail::Event skelcl::Vector< T >::startDownload | ( | ) | const |
Starts copying data from the devices involved in the current distribution to the host.
This function returns immediately and does not wait until the copy operation is finished. The event object returned can be used to wait explicitly for the copy operation to complete. For an blocking version use copyDataToHost().
Complexity Linear in the number of devices (usually small). This function does not block until the operation is finished.
detail::Event skelcl::Vector< T >::startUpload | ( | ) | const |
Starts copying data from the host to the devices involved in the current distribution.
This function returns immediately and does not wait until the copy operation is finished. The event object returned can be used to wait explicitly for the copy operation to complete. For an blocking version use copyDataToDevices().
Complexity Linear in the number of devices (usually small). This function does not block until the operation is finished.
void skelcl::Vector< T >::swap | ( | Vector< T > & | rhs | ) |
Exchanges the contents of the Vectors with those of rhs
.
Does not invoke any move, copy, or swap operations on individual elements.
Complexity Constant
rhs | Vector to exchange the contents with |