libMesh::StoredRange< iterator_type, object_type > Class Template Reference

Utility class for defining generic ranges for threading. More...

#include <stored_range.h>

Public Types

typedef std::vector< object_type >::const_iterator const_iterator
 

Public Member Functions

 StoredRange (const unsigned int new_grainsize=1000)
 
 StoredRange (const iterator_type &first, const iterator_type &last, const unsigned int new_grainsize=1000)
 
 StoredRange (std::vector< object_type > *objs, const unsigned int new_grainsize=1000)
 
 StoredRange (const StoredRange< iterator_type, object_type > &er)
 
 StoredRange (const StoredRange< iterator_type, object_type > &er, const const_iterator &begin_range, const const_iterator &end_range)
 
 StoredRange (StoredRange< iterator_type, object_type > &r, Threads::split)
 
 ~StoredRange ()
 
StoredRange< iterator_type, object_type > & reset (const iterator_type &first, const iterator_type &last)
 
StoredRange< iterator_type, object_type > & reset ()
 
const_iterator begin () const
 
const_iterator end () const
 
std::size_t first_idx () const
 
std::size_t last_idx () const
 
std::size_t grainsize () const
 
void grainsize (const unsigned int &gs)
 
std::size_t size () const
 
bool empty () const
 
bool is_divisible () const
 

Private Attributes

const_iterator _end
 
const_iterator _begin
 
std::size_t _last
 
std::size_t _first
 
std::size_t _grainsize
 
std::vector< object_type > * _objs
 
bool _should_release
 

Detailed Description

template<typename iterator_type, typename object_type>
class libMesh::StoredRange< iterator_type, object_type >

Utility class for defining generic ranges for threading.

The StoredRange class defines a contiguous, divisible set of objects. This class is used primarily as the argument to function objects. The range can then be subdivided into a number of "tasks" which can be executed in parallel. This concept is central to the Threading Building Blocks template library which can optionally be used by libMesh to implement shared-memory parallelism.

The implementation takes a user-provided object range and packs it into a contiguous vector which can then be subdivided efficiently. A first-cut implementation using raw element iterators incurred simply too much overhead by using the predicated iterators, specifically operations such as advancing such iterators has a cost proportional to the amount the iterator is advanced. Hence in this implementation the user-provided range is packed into a vector.

Author
Benjamin S. Kirk
Date
2008

Definition at line 52 of file stored_range.h.

Member Typedef Documentation

template<typename iterator_type, typename object_type>
typedef std::vector<object_type>::const_iterator libMesh::StoredRange< iterator_type, object_type >::const_iterator

Allows an StoredRange to behave like an STL container.

Definition at line 58 of file stored_range.h.

Constructor & Destructor Documentation

template<typename iterator_type, typename object_type>
libMesh::StoredRange< iterator_type, object_type >::StoredRange ( const unsigned int  new_grainsize = 1000)
inline

Constructor. Optionally takes the grainsize parameter, which is the smallest chunk the range may be broken into for parallel execution.

Definition at line 65 of file stored_range.h.

65  :
66  _end(),
67  _begin(),
68  _last(),
69  _first(),
70  _grainsize(new_grainsize),
71  _objs(new std::vector<object_type>()),
72  _should_release(true)
73  {}
const_iterator _begin
Definition: stored_range.h:311
std::vector< object_type > * _objs
Definition: stored_range.h:317
const_iterator _end
Definition: stored_range.h:310
std::size_t _grainsize
Definition: stored_range.h:314
template<typename iterator_type, typename object_type>
libMesh::StoredRange< iterator_type, object_type >::StoredRange ( const iterator_type &  first,
const iterator_type &  last,
const unsigned int  new_grainsize = 1000 
)
inline

Constructor. Takes the beginning and end of the range. Optionally takes the grainsize parameter, which is the smallest chunk the range may be broken into for parallel execution.

Definition at line 81 of file stored_range.h.

References libMesh::StoredRange< iterator_type, object_type >::reset().

83  :
84  _end(),
85  _begin(),
86  _last(),
87  _first(),
88  _grainsize(new_grainsize),
89  _objs(new std::vector<object_type>()),
90  _should_release(true)
91  {
92  this->reset(first, last);
93  }
const_iterator _begin
Definition: stored_range.h:311
std::vector< object_type > * _objs
Definition: stored_range.h:317
const_iterator _end
Definition: stored_range.h:310
std::size_t _grainsize
Definition: stored_range.h:314
StoredRange< iterator_type, object_type > & reset()
Definition: stored_range.h:247
template<typename iterator_type, typename object_type>
libMesh::StoredRange< iterator_type, object_type >::StoredRange ( std::vector< object_type > *  objs,
const unsigned int  new_grainsize = 1000 
)
inline

Constructor. Takes a std::vector of objects. Optionally takes the grainsize parameter, which is the smallest chunk the range may be broken into for parallel execution.

Note
The std::vector passed in here MUST live for the lifetime of this StoredRange!
Todo:
This should be a std::shared_ptr in the future!

Definition at line 106 of file stored_range.h.

107  :
108  _end(objs->end()),
109  _begin(objs->begin()),
110  _last(objs->size()),
111  _first(0),
112  _grainsize(new_grainsize),
113  _objs(objs),
114  _should_release(false)
115  {
116  }
const_iterator _begin
Definition: stored_range.h:311
std::vector< object_type > * _objs
Definition: stored_range.h:317
const_iterator _end
Definition: stored_range.h:310
std::size_t _grainsize
Definition: stored_range.h:314
template<typename iterator_type, typename object_type>
libMesh::StoredRange< iterator_type, object_type >::StoredRange ( const StoredRange< iterator_type, object_type > &  er)
inline

Copy constructor. The StoredRange can be copied into subranges for parallel execution. In this way the initial StoredRange can be thought of as the root of a binary tree. The root element is the only element which interacts with the user. It takes a specified range of objects and packs it into a contiguous vector which can be split efficiently. However, there is no need for the child ranges to contain this vector, so long as the parent outlives the children. So we implement the copy constructor to specifically omit the _objs vector.

Definition at line 131 of file stored_range.h.

131  :
132  _end(er._end),
133  _begin(er._begin),
134  _last(er._last),
135  _first(er._first),
136  _grainsize(er._grainsize),
137  _objs(NULL),
138  _should_release(false)
139  {
140  // specifically, do *not* copy the vector
141  }
const_iterator _begin
Definition: stored_range.h:311
std::vector< object_type > * _objs
Definition: stored_range.h:317
const_iterator _end
Definition: stored_range.h:310
std::size_t _grainsize
Definition: stored_range.h:314
template<typename iterator_type, typename object_type>
libMesh::StoredRange< iterator_type, object_type >::StoredRange ( const StoredRange< iterator_type, object_type > &  er,
const const_iterator begin_range,
const const_iterator end_range 
)
inline

NOTE: When using pthreads this constructor is MANDATORY!!!

Copy constructor. The StoredRange can be copied into subranges for parallel execution. In this way the initial StoredRange can be thought of as the root of a binary tree. The root element is the only element which interacts with the user. It takes a specified range of objects and packs it into a contiguous vector which can be split efficiently. However, there is no need for the child ranges to contain this vector, so long as the parent outlives the children. So we implement the copy constructor to specifically omit the _objs vector. This version allows you to set the beginning and ending of this new range to be different from that of the one we're copying.

Definition at line 160 of file stored_range.h.

References libMesh::StoredRange< iterator_type, object_type >::_begin, libMesh::StoredRange< iterator_type, object_type >::_end, libMesh::StoredRange< iterator_type, object_type >::_first, and libMesh::StoredRange< iterator_type, object_type >::_last.

162  :
163  _end(end_range),
164  _begin(begin_range),
165  _last(0), // Initialize these in a moment
166  _first(0),
167  _grainsize(er._grainsize),
168  _objs(NULL),
169  _should_release(false)
170  {
171  // specifically, do *not* copy the vector
172 
173  _first = std::distance(er._begin, _begin);
174  _last = _first + std::distance(_begin, _end);
175  }
const_iterator _begin
Definition: stored_range.h:311
std::vector< object_type > * _objs
Definition: stored_range.h:317
const_iterator _end
Definition: stored_range.h:310
std::size_t _grainsize
Definition: stored_range.h:314
template<typename iterator_type, typename object_type>
libMesh::StoredRange< iterator_type, object_type >::StoredRange ( StoredRange< iterator_type, object_type > &  r,
Threads::split   
)
inline

Splits the range r. The first half of the range is left in place, the second half of the range is placed in *this.

Definition at line 182 of file stored_range.h.

References libMesh::StoredRange< iterator_type, object_type >::_begin, libMesh::StoredRange< iterator_type, object_type >::_end, libMesh::StoredRange< iterator_type, object_type >::_first, and libMesh::StoredRange< iterator_type, object_type >::_last.

182  :
183  _end(r._end),
184  _begin(r._begin),
185  _last(r._last),
186  _first(r._first),
187  _grainsize(r._grainsize),
188  _objs(NULL),
189  _should_release(false)
190  {
192  beginning = r._begin,
193  ending = r._end,
194  middle = beginning + std::distance(beginning, ending)/2u;
195 
196  r._end = _begin = middle;
197 
198  std::size_t
199  first = r._first,
200  last = r._last,
201  half = first + (last-first)/2u;
202 
203  r._last = _first = half;
204  }
const_iterator _begin
Definition: stored_range.h:311
std::vector< object_type > * _objs
Definition: stored_range.h:317
const_iterator _end
Definition: stored_range.h:310
std::vector< object_type >::const_iterator const_iterator
Definition: stored_range.h:58
std::size_t _grainsize
Definition: stored_range.h:314
template<typename iterator_type, typename object_type>
libMesh::StoredRange< iterator_type, object_type >::~StoredRange ( )
inline

Destructor. Releases the object array if we created it.

Definition at line 209 of file stored_range.h.

References libMesh::StoredRange< iterator_type, object_type >::_objs, and libMesh::StoredRange< iterator_type, object_type >::_should_release.

210  {
211  if (_should_release)
212  delete _objs;
213  }
std::vector< object_type > * _objs
Definition: stored_range.h:317

Member Function Documentation

template<typename iterator_type, typename object_type>
bool libMesh::StoredRange< iterator_type, object_type >::empty ( ) const
inline
Returns
true if the range is empty.

Definition at line 301 of file stored_range.h.

References libMesh::StoredRange< iterator_type, object_type >::_begin, and libMesh::StoredRange< iterator_type, object_type >::_end.

Referenced by libMesh::DofMap::create_dof_constraints().

301 { return (_begin == _end); }
const_iterator _begin
Definition: stored_range.h:311
const_iterator _end
Definition: stored_range.h:310
template<typename iterator_type, typename object_type>
std::size_t libMesh::StoredRange< iterator_type, object_type >::first_idx ( ) const
inline

Index in the stored vector of the first object.

Definition at line 271 of file stored_range.h.

References libMesh::StoredRange< iterator_type, object_type >::_first.

271 { return _first; }
template<typename iterator_type, typename object_type>
std::size_t libMesh::StoredRange< iterator_type, object_type >::grainsize ( ) const
inline

The grain size for the range. The range will be subdivided into subranges not to exceed the grain size.

Definition at line 282 of file stored_range.h.

References libMesh::StoredRange< iterator_type, object_type >::_grainsize.

Referenced by libMesh::StoredRange< iterator_type, object_type >::is_divisible().

282 {return _grainsize;}
std::size_t _grainsize
Definition: stored_range.h:314
template<typename iterator_type, typename object_type>
void libMesh::StoredRange< iterator_type, object_type >::grainsize ( const unsigned int &  gs)
inline

Set the grain size.

Definition at line 287 of file stored_range.h.

References libMesh::StoredRange< iterator_type, object_type >::_grainsize.

287 {_grainsize = gs;}
std::size_t _grainsize
Definition: stored_range.h:314
template<typename iterator_type, typename object_type>
bool libMesh::StoredRange< iterator_type, object_type >::is_divisible ( ) const
inline
Returns
true if the range can be subdivided.

Definition at line 306 of file stored_range.h.

References libMesh::StoredRange< iterator_type, object_type >::_begin, libMesh::StoredRange< iterator_type, object_type >::_end, and libMesh::StoredRange< iterator_type, object_type >::grainsize().

306 { return this->grainsize() < static_cast<unsigned int>(std::distance(_begin, _end)); }
const_iterator _begin
Definition: stored_range.h:311
const_iterator _end
Definition: stored_range.h:310
std::size_t grainsize() const
Definition: stored_range.h:282
template<typename iterator_type, typename object_type>
std::size_t libMesh::StoredRange< iterator_type, object_type >::last_idx ( ) const
inline

Index in the stored vector of the last object.

Definition at line 276 of file stored_range.h.

References libMesh::StoredRange< iterator_type, object_type >::_last.

276 { return _last; }
template<typename iterator_type, typename object_type>
StoredRange<iterator_type, object_type>& libMesh::StoredRange< iterator_type, object_type >::reset ( const iterator_type &  first,
const iterator_type &  last 
)
inline

Resets the StoredRange to contain [first,last).

Returns
A reference to itself for convenience, so functions expecting a StoredRange<> can be passed e.g. foo.reset(begin,end).

Definition at line 222 of file stored_range.h.

References libMesh::StoredRange< iterator_type, object_type >::_begin, libMesh::StoredRange< iterator_type, object_type >::_end, libMesh::StoredRange< iterator_type, object_type >::_first, libMesh::StoredRange< iterator_type, object_type >::_last, and libMesh::StoredRange< iterator_type, object_type >::_objs.

Referenced by libMesh::FEMSystem::assemble_qoi(), libMesh::FEMSystem::assemble_qoi_derivative(), libMesh::FEMSystem::assembly(), libMesh::DofMap::create_dof_constraints(), and libMesh::FEMSystem::postprocess().

224  {
225  _objs->clear();
226 
227  for (iterator_type it=first; it!=last; ++it)
228  _objs->push_back(*it);
229 
230  _begin = _objs->begin();
231  _end = _objs->end();
232 
233  _first = 0;
234  _last = _objs->size();
235 
236  return *this;
237  }
const_iterator _begin
Definition: stored_range.h:311
std::vector< object_type > * _objs
Definition: stored_range.h:317
const_iterator _end
Definition: stored_range.h:310
template<typename iterator_type, typename object_type>
StoredRange<iterator_type, object_type>& libMesh::StoredRange< iterator_type, object_type >::reset ( )
inline

Resets the range to the last specified range. This method only exists for efficiency – it is more efficient to set the range to its previous value without rebuilding the underlying vector.

Returns
A reference to itself for convenience, so functions expecting a StoredRange<> can be passed e.g. foo.reset().

Definition at line 247 of file stored_range.h.

References libMesh::StoredRange< iterator_type, object_type >::_begin, libMesh::StoredRange< iterator_type, object_type >::_end, libMesh::StoredRange< iterator_type, object_type >::_first, libMesh::StoredRange< iterator_type, object_type >::_last, and libMesh::StoredRange< iterator_type, object_type >::_objs.

Referenced by libMesh::StoredRange< iterator_type, object_type >::StoredRange().

248  {
249  _begin = _objs->begin();
250  _end = _objs->end();
251 
252  _first = 0;
253  _last = _objs->size();
254 
255  return *this;
256  }
const_iterator _begin
Definition: stored_range.h:311
std::vector< object_type > * _objs
Definition: stored_range.h:317
const_iterator _end
Definition: stored_range.h:310
template<typename iterator_type, typename object_type>
std::size_t libMesh::StoredRange< iterator_type, object_type >::size ( ) const
inline
Returns
The size of the range.

Definition at line 292 of file stored_range.h.

References libMesh::StoredRange< iterator_type, object_type >::_begin, and libMesh::StoredRange< iterator_type, object_type >::_end.

292 { return std::distance(_begin, _end); }
const_iterator _begin
Definition: stored_range.h:311
const_iterator _end
Definition: stored_range.h:310

Member Data Documentation

template<typename iterator_type, typename object_type>
std::size_t libMesh::StoredRange< iterator_type, object_type >::_first
private
template<typename iterator_type, typename object_type>
std::size_t libMesh::StoredRange< iterator_type, object_type >::_grainsize
private
template<typename iterator_type, typename object_type>
std::size_t libMesh::StoredRange< iterator_type, object_type >::_last
private
template<typename iterator_type, typename object_type>
std::vector<object_type>* libMesh::StoredRange< iterator_type, object_type >::_objs
private
template<typename iterator_type, typename object_type>
bool libMesh::StoredRange< iterator_type, object_type >::_should_release
private

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