Container Data Access

Ranges provide access to data stored in containers as regular C++ data.

Containers (see Dense Containers, Nested Containers) in Intel(R) Array Building Blocks (Intel(R) ArBB) hide their data representation. This allows Intel(R) ArBB to control the location and layout of the memory used to store the data. When Intel(R) ArBB operations such as element-wise functions (see Scalar and Element-wise Functions) are applied to a container, Intel(R) ArBB uses its internal knowledge of the containers to access the data. To access data in a container from regular C++ code, you must use a range obtained from that container. The arbb::range and arbb::const_range types represent such ranges and act like standard C++ containers with functions such as arbb::range::begin() and arbb::range::end().

Dense containers provide the following member functions to access their data as ranges:

Use the most restrictive member function sufficient for your needs. For example, if the result of a computation is stored in a container and you only need to read it, use arbb::dense::read_only_range(). This allows Intel(R) ArBB to avoid unnecessary synchronization.

After obtaining a range, you can access elements within it directly from the range using arbb::range::operator[] or using iterators obtained by functions such as arbb::range::begin() and arbb::range::end(). The iterators returned from ranges can be used as random-access iterators such as those obtained from std::vector.

The elements obtained from ranges are plain uncaptured C++ types (see arbb::uncaptured) matching the element type of the corresponding container. For example, dereferencing a range iterator from an arbb::dense<arbb::f32> container yields float elements.

The following code example illustrates how you can use ranges:

 arbb::dense<arbb::f32> foo(...);

 // Construct a range that can be read from and written to.
 arbb::range<arbb::f32> rw_range = foo.read_write_range();
 rw_range[0] = 1.0f; // Set first element to 1.0f.
 float second_element = rw_range[1]; // Read value of second element.

 // Construct a range that can only be read.
 arbb::const_range<arbb::f32> read_range = foo.read_only_range();
 float third_element = read_range[2]; // Read value of third element.

 // Use range iterators.
 arbb::const_range<arbb::f32>::iterator begin = read_range.begin();
 arbb::const_range<arbb::f32>::iterator end = read_range.end();
 
 for (arbb::range<arbb::f32>::iterator I = begin; I != end; ++I) {
   std::cout << *I << std::endl; // Print each element in the range.
 }

 // Fill entire range with zeros.
 std::fill(rw_range.begin(), rw_range.end(), 0.0f);

Creating a range may involve synchronization, such as copying data from a remote accelerator to the host processor, so ranges are only valid for a limited amount of time. A range obtained from a container C is valid from when it is construction until the next Intel(R) ArBB operation involving C.

The following code example illustrates range validity:

 arbb::dense<arbb::f32> container(...);

 // Obtain a range from the container.
 arbb::range<arbb::f32> range1 = container.read_write_range();

 // Fill entire range with zeroes.
 std::fill(rw_range.begin(), rw_range.end(), 0.0f);

 // Call a function that uses the given container.
 // range1 is now invalid.
 arbb::call(some_function)(container);

 // At this point, it is no longer safe to perform any operations
 // on range1.

 // Obtain another range from the container.
 arbb::range<arbb::f32> range2 = container.read_write_range();

 // Output the first element from the range.
 std::cout << range2[0] << std::endl;

 // Perform another operation on the container.
 // range2 is now invalid.
 container += container;

 // At this point, it is no longer safe to perform any operations
 // on range1 or range2.

See Also

Dense Containers
Nested Containers
Container Bindings
arbb::dense::read_write_range()
arbb::dense::read_only_range()
arbb::dense::write_only_range()

Classes

class  arbb::range< T >
 A pair of iterators pointing to the beginning and the end of a data range that can be modified. More...
class  arbb::const_range< T >
 A pair of iterators pointing to the beginning and end of a range of data that can not be modified. More...
class  arbb::range_iterator< T >
 An iterator obtained from an arbb::range instance pointing to mutable elements. More...
class  arbb::const_range_iterator< T >
 An iterator obtained from an arbb::range instance pointing to constant elements. More...

Functions

template<typename T >
bool arbb::operator== (const range_iterator< T > &a, const range_iterator< T > &b)
 Returns true if a points to the same element as b.
template<typename T >
bool arbb::operator== (const const_range_iterator< T > &a, const const_range_iterator< T > &b)
 Returns true if a points to the same element as b.
template<typename T >
bool arbb::operator!= (const range_iterator< T > &a, const range_iterator< T > &b)
 Returns true if a points to a different element than b.
template<typename T >
bool arbb::operator!= (const const_range_iterator< T > &a, const const_range_iterator< T > &b)
 Returns true if a points to a different element than b.
template<typename T >
bool arbb::operator< (const range_iterator< T > &a, const range_iterator< T > &b)
 Returns true if a points to an element earlier in the range than b.
template<typename T >
bool arbb::operator< (const const_range_iterator< T > &a, const const_range_iterator< T > &b)
 Returns true if a points to an element earlier in the range than b.
template<typename T >
bool arbb::operator<= (const range_iterator< T > &a, const range_iterator< T > &b)
 Returns true if a points to an element earlier in the range than or at the same location as b.
template<typename T >
bool arbb::operator<= (const const_range_iterator< T > &a, const const_range_iterator< T > &b)
 Returns true if a points to an element earlier in the range than or at the same location as b.
template<typename T >
bool arbb::operator> (const range_iterator< T > &a, const range_iterator< T > &b)
 Returns true if a points to an element later in the range than b.
template<typename T >
bool arbb::operator> (const const_range_iterator< T > &a, const const_range_iterator< T > &b)
 Returns true if a points to an element later in the range than b.
template<typename T >
bool arbb::operator>= (const range_iterator< T > &a, const range_iterator< T > &b)
 Returns true if a points to an element later in the range than or at the same location as b.
template<typename T >
bool arbb::operator>= (const const_range_iterator< T > &a, const const_range_iterator< T > &b)
 Returns true if a points to an element later in the range than or at the same location as b.
template<typename T >
range_iterator< T > arbb::operator+ (range_iterator< T > a, typename range_iterator< T >::difference_type b)
 Returns an iterator offset b elements from a.
template<typename T >
const_range_iterator< T > arbb::operator+ (const_range_iterator< T > a, typename const_range_iterator< T >::difference_type b)
 Returns an iterator offset b elements from a.
template<typename T >
range_iterator< T > arbb::operator+ (typename range_iterator< T >::difference_type a, range_iterator< T > b)
 Returns an iterator offset a elements from b.
template<typename T >
const_range_iterator< T > arbb::operator+ (typename const_range_iterator< T >::difference_type a, const_range_iterator< T > b)
 Returns an iterator offset a elements from b.
template<typename T >
range_iterator< T >
::difference_type 
arbb::operator- (range_iterator< T > a, range_iterator< T > b)
 Returns the offset added to b to obtain a.
template<typename T >
const_range_iterator< T >
::difference_type 
arbb::operator- (const_range_iterator< T > a, const_range_iterator< T > b)
 Returns the offset added to b to obtain a.
template<typename T >
range_iterator< T > arbb::operator- (range_iterator< T > a, typename range_iterator< T >::difference_type b)
 Returns an iterator offset -b elements from a.
template<typename T >
const_range_iterator< T > arbb::operator- (const_range_iterator< T > a, typename const_range_iterator< T >::difference_type b)
 Returns an iterator offset -b elements from a.

Function Documentation

template<typename T >
bool arbb::operator== ( const range_iterator< T > &  a,
const range_iterator< T > &  b 
) [inline]

Returns true if a points to the same element as b.

If a and b point to elements in different ranges, calling this function causes undefined behavior.

Definition at line 32 of file range_iterator_funcs.hpp.

template<typename T >
bool arbb::operator== ( const const_range_iterator< T > &  a,
const const_range_iterator< T > &  b 
) [inline]

Returns true if a points to the same element as b.

If a and b point to elements in different ranges, calling this function causes undefined behavior.

Definition at line 41 of file range_iterator_funcs.hpp.

template<typename T >
bool arbb::operator!= ( const range_iterator< T > &  a,
const range_iterator< T > &  b 
) [inline]

Returns true if a points to a different element than b.

If a and b point to elements in different ranges, calling this function causes undefined behavior.

Definition at line 50 of file range_iterator_funcs.hpp.

template<typename T >
bool arbb::operator!= ( const const_range_iterator< T > &  a,
const const_range_iterator< T > &  b 
) [inline]

Returns true if a points to a different element than b.

If a and b point to elements in different ranges, calling this function causes undefined behavior.

Definition at line 59 of file range_iterator_funcs.hpp.

template<typename T >
bool arbb::operator< ( const range_iterator< T > &  a,
const range_iterator< T > &  b 
) [inline]

Returns true if a points to an element earlier in the range than b.

If a and b point to elements in different ranges, calling this function causes undefined behavior.

Definition at line 69 of file range_iterator_funcs.hpp.

template<typename T >
bool arbb::operator< ( const const_range_iterator< T > &  a,
const const_range_iterator< T > &  b 
) [inline]

Returns true if a points to an element earlier in the range than b.

If a and b point to elements in different ranges, calling this function causes undefined behavior.

Definition at line 79 of file range_iterator_funcs.hpp.

template<typename T >
bool arbb::operator<= ( const range_iterator< T > &  a,
const range_iterator< T > &  b 
) [inline]

Returns true if a points to an element earlier in the range than or at the same location as b.

If a and b point to elements in different ranges, calling this function causes undefined behavior.

Definition at line 89 of file range_iterator_funcs.hpp.

template<typename T >
bool arbb::operator<= ( const const_range_iterator< T > &  a,
const const_range_iterator< T > &  b 
) [inline]

Returns true if a points to an element earlier in the range than or at the same location as b.

If a and b point to elements in different ranges, calling this function causes undefined behavior.

Definition at line 99 of file range_iterator_funcs.hpp.

template<typename T >
bool arbb::operator> ( const range_iterator< T > &  a,
const range_iterator< T > &  b 
) [inline]

Returns true if a points to an element later in the range than b.

If a and b point to elements in different ranges, calling this function causes undefined behavior.

Definition at line 109 of file range_iterator_funcs.hpp.

template<typename T >
bool arbb::operator> ( const const_range_iterator< T > &  a,
const const_range_iterator< T > &  b 
) [inline]

Returns true if a points to an element later in the range than b.

If a and b point to elements in different ranges, calling this function causes undefined behavior.

Definition at line 119 of file range_iterator_funcs.hpp.

template<typename T >
bool arbb::operator>= ( const range_iterator< T > &  a,
const range_iterator< T > &  b 
) [inline]

Returns true if a points to an element later in the range than or at the same location as b.

If a and b point to elements in different ranges, calling this function causes undefined behavior.

Definition at line 129 of file range_iterator_funcs.hpp.

template<typename T >
bool arbb::operator>= ( const const_range_iterator< T > &  a,
const const_range_iterator< T > &  b 
) [inline]

Returns true if a points to an element later in the range than or at the same location as b.

If a and b point to elements in different ranges, calling this function causes undefined behavior.

Definition at line 139 of file range_iterator_funcs.hpp.

template<typename T >
range_iterator<T> arbb::operator+ ( range_iterator< T >  a,
typename range_iterator< T >::difference_type  b 
) [inline]

Returns an iterator offset b elements from a.

Definition at line 146 of file range_iterator_funcs.hpp.

template<typename T >
const_range_iterator<T> arbb::operator+ ( const_range_iterator< T >  a,
typename const_range_iterator< T >::difference_type  b 
) [inline]

Returns an iterator offset b elements from a.

Definition at line 153 of file range_iterator_funcs.hpp.

template<typename T >
range_iterator<T> arbb::operator+ ( typename range_iterator< T >::difference_type  a,
range_iterator< T >  b 
) [inline]

Returns an iterator offset a elements from b.

Definition at line 160 of file range_iterator_funcs.hpp.

template<typename T >
const_range_iterator<T> arbb::operator+ ( typename const_range_iterator< T >::difference_type  a,
const_range_iterator< T >  b 
) [inline]

Returns an iterator offset a elements from b.

Definition at line 167 of file range_iterator_funcs.hpp.

template<typename T >
range_iterator<T>::difference_type arbb::operator- ( range_iterator< T >  a,
range_iterator< T >  b 
) [inline]

Returns the offset added to b to obtain a.

Equivalent to a.difference(b). If a and b point to elements in different ranges, calling this function causes undefined behavior.

Definition at line 177 of file range_iterator_funcs.hpp.

template<typename T >
const_range_iterator<T>::difference_type arbb::operator- ( const_range_iterator< T >  a,
const_range_iterator< T >  b 
) [inline]

Returns the offset added to b to obtain a.

Equivalent to a.difference(b). If a and b point to elements in different ranges, calling this function causes undefined behavior.

Definition at line 187 of file range_iterator_funcs.hpp.

template<typename T >
range_iterator<T> arbb::operator- ( range_iterator< T >  a,
typename range_iterator< T >::difference_type  b 
) [inline]

Returns an iterator offset -b elements from a.

Definition at line 194 of file range_iterator_funcs.hpp.

template<typename T >
const_range_iterator<T> arbb::operator- ( const_range_iterator< T >  a,
typename const_range_iterator< T >::difference_type  b 
) [inline]

Returns an iterator offset -b elements from a.

Definition at line 201 of file range_iterator_funcs.hpp.

Submit feedback on this help topic

Copyright © 2010, Intel Corporation. All rights reserved.