The StoredRange class defines a contiguous, divisible set of objects. More...

#include <stored_range.h>

Public Types
typedef std::vector< object_type >	vec_type
	Allows an `StoredRange` to behave like an STL container.

typedef vec_type::const_iterator	const_iterator

typedef std::unique_ptr< vec_type, std::function< void(vec_type *)> >	ptr_type

Public Member Functions
	StoredRange (const unsigned int new_grainsize=libMesh::default_grainsize())
	Constructor.

	StoredRange (const iterator_type &first, const iterator_type &last, const unsigned int new_grainsize=libMesh::default_grainsize())
	Constructor.

	StoredRange (vec_type *objs, const unsigned int new_grainsize=libMesh::default_grainsize())
	Constructor.

	StoredRange (const StoredRange< iterator_type, object_type > &er)
	Copy constructor.

	StoredRange (const StoredRange< iterator_type, object_type > &er, const const_iterator &begin_range, const const_iterator &end_range)
	NOTE: When using pthreads this constructor is MANDATORY!!!

	StoredRange (StoredRange< iterator_type, object_type > &r, Threads::split)
	Splits the range `r`.

	~StoredRange ()=default
	Destructor.

StoredRange< iterator_type, object_type > &	reset (const iterator_type &first, const iterator_type &last)
	Resets the `StoredRange` to contain [first,last).

StoredRange< iterator_type, object_type > &	reset ()
	Resets the range to the last specified range.

const_iterator	begin () const
	Beginning of the range.

const_iterator	end () const
	End of the range.

std::size_t	first_idx () const
	Index in the stored vector of the first object.

std::size_t	last_idx () const
	Index in the stored vector of the last object.

std::size_t	grainsize () const
	The grain size for the range.

void	grainsize (const unsigned int &gs)
	Set the grain size.

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

ptr_type	_objs

Detailed Description

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

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

Utility class for defining generic ranges for threading.

Definition at line 54 of file stored_range.h.

Member Typedef Documentation

◆ const_iterator

template<typename iterator_type , typename object_type >

typedef vec_type::const_iterator libMesh::StoredRange< iterator_type, object_type >::const_iterator

Definition at line 61 of file stored_range.h.

◆ ptr_type

template<typename iterator_type , typename object_type >

typedef std::unique_ptr<vec_type, std::function<void (vec_type *)> > libMesh::StoredRange< iterator_type, object_type >::ptr_type

Definition at line 62 of file stored_range.h.

◆ vec_type

template<typename iterator_type , typename object_type >

typedef std::vector<object_type> libMesh::StoredRange< iterator_type, object_type >::vec_type

Allows an StoredRange to behave like an STL container.

Definition at line 60 of file stored_range.h.

Constructor & Destructor Documentation

◆ StoredRange() [1/6]

template<typename iterator_type , typename object_type >

libMesh::StoredRange< iterator_type, object_type >::StoredRange ( const unsigned int new_grainsize = libMesh::default_grainsize() )

inline

Constructor.

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

Definition at line 69 of file stored_range.h.

                                                                              :
    _end(),
    _begin(),
    _last(),
    _first(),
    _grainsize(new_grainsize),
    _objs(ptr_type(new vec_type(), [](vec_type * p){delete p;}))
  {}

◆ StoredRange() [2/6]

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 = `libMesh::default_grainsize()`
	)

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 84 of file stored_range.h.

                                                                              :
    _end(),
    _begin(),
    _last(),
    _first(),
    _grainsize(new_grainsize),
    _objs(ptr_type(new vec_type(), [](vec_type * p){delete p;}))
  {
    this->reset(first, last);
  }

◆ StoredRange() [3/6]

template<typename iterator_type , typename object_type >

libMesh::StoredRange< iterator_type, object_type >::StoredRange	(	vec_type *	objs,
		const unsigned int	new_grainsize = `libMesh::default_grainsize()`
	)

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! We are not responsible for deleting this pointer.

Definition at line 107 of file stored_range.h.

                                                                              :
    _end(objs->end()),
    _begin(objs->begin()),
    _last(objs->size()),
    _first(0),
    _grainsize(new_grainsize),
    _objs(ptr_type(objs, [](vec_type *){/*don't delete*/}))
  {
  }

◆ StoredRange() [4/6]

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.

                                                                 :
    _end(er._end),
    _begin(er._begin),
    _last(er._last),
    _first(er._first),
    _grainsize(er._grainsize),
    _objs(nullptr)
  {
    // specifically, do *not* copy the vector
  }

◆ StoredRange() [5/6]

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 159 of file stored_range.h.

                                                :
    _end(end_range),
    _begin(begin_range),
    _last(0), // Initialize these in a moment
    _first(0),
    _grainsize(er._grainsize),
    _objs(nullptr)
  {
    // specifically, do *not* copy the vector
 
    _first = std::distance(er._begin, _begin);
    _last = _first + std::distance(_begin, _end);
  }

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.

◆ StoredRange() [6/6]

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 180 of file stored_range.h.

                                                                          :
    _end(r._end),
    _begin(r._begin),
    _last(r._last),
    _first(r._first),
    _grainsize(r._grainsize),
    _objs(nullptr)
  {
    const_iterator
      beginning = r._begin,
      ending    = r._end,
      middle    = beginning + std::distance(beginning, ending)/2u;
 
    r._end = _begin = middle;
 
    std::size_t
      first = r._first,
      last  = r._last,
      half  = first + (last-first)/2u;
 
    r._last = _first = half;
  }

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.

◆ ~StoredRange()

template<typename iterator_type , typename object_type >

libMesh::StoredRange< iterator_type, object_type >::~StoredRange ( )

default

Destructor.

Releases the object array if we created it.

Member Function Documentation

◆ begin()

template<typename iterator_type , typename object_type >

const_iterator libMesh::StoredRange< iterator_type, object_type >::begin ( ) const

inline

Beginning of the range.

Definition at line 260 of file stored_range.h.

260{ return _begin; }

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

◆ empty()

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 300 of file stored_range.h.

300{ return (_begin == _end); }

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

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

◆ end()

template<typename iterator_type , typename object_type >

const_iterator libMesh::StoredRange< iterator_type, object_type >::end ( ) const

inline

End of the range.

Definition at line 265 of file stored_range.h.

265{ return _end; }

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

◆ first_idx()

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 270 of file stored_range.h.

270{ return _first; }

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

◆ grainsize() [1/2]

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 281 of file stored_range.h.

281{return _grainsize;}

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

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

◆ grainsize() [2/2]

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 286 of file stored_range.h.

286{_grainsize = gs;}

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

◆ is_divisible()

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 305 of file stored_range.h.

305{ return this->grainsize() < static_cast<unsigned int>(std::distance(_begin, _end)); }

libMesh::StoredRange::grainsize

std::size_t grainsize() const

The grain size for the range.

Definition stored_range.h:281

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

◆ last_idx()

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 275 of file stored_range.h.

275{ return _last; }

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

◆ reset() [1/2]

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 243 of file stored_range.h.

  {
    // _objs must be initialized in order to call reset()
    libmesh_assert(_objs);
 
    _begin = _objs->begin();
    _end   = _objs->end();
 
    _first = 0;
    _last  = _objs->size();
 
    return *this;
  }

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, libMesh::StoredRange< iterator_type, object_type >::_objs, and libMesh::libmesh_assert().

◆ reset() [2/2]

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 215 of file stored_range.h.

  {
    // _objs must be initialized in order to call reset()
    libmesh_assert(_objs);
 
    _objs->clear();
 
    for (iterator_type it=first; it!=last; ++it)
      _objs->push_back(*it);
 
    _begin = _objs->begin();
    _end   = _objs->end();
 
    _first = 0;
    _last  = _objs->size();
 
    return *this;
  }

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, libMesh::StoredRange< iterator_type, object_type >::_objs, and libMesh::libmesh_assert().

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

◆ size()

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 291 of file stored_range.h.

291{ return std::distance(_begin, _end); }

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

Referenced by libMesh::MeshCommunication::assign_global_indices(), and libMesh::MeshCommunication::check_for_duplicate_global_indices().

Member Data Documentation

◆ _begin

template<typename iterator_type , typename object_type >

const_iterator libMesh::StoredRange< iterator_type, object_type >::_begin

private

Definition at line 310 of file stored_range.h.

◆ _end

template<typename iterator_type , typename object_type >

const_iterator libMesh::StoredRange< iterator_type, object_type >::_end

private

Definition at line 309 of file stored_range.h.

◆ _first

template<typename iterator_type , typename object_type >

std::size_t libMesh::StoredRange< iterator_type, object_type >::_first

private

Definition at line 312 of file stored_range.h.

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

◆ _grainsize

template<typename iterator_type , typename object_type >

std::size_t libMesh::StoredRange< iterator_type, object_type >::_grainsize

private

Definition at line 313 of file stored_range.h.

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

◆ _last

template<typename iterator_type , typename object_type >

std::size_t libMesh::StoredRange< iterator_type, object_type >::_last

private

Definition at line 311 of file stored_range.h.

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

◆ _objs

template<typename iterator_type , typename object_type >

ptr_type libMesh::StoredRange< iterator_type, object_type >::_objs

private

Definition at line 315 of file stored_range.h.

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

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

include/geom/stored_range.h

Public Types

Public Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ const_iterator

◆ ptr_type

◆ vec_type

Constructor & Destructor Documentation

◆ StoredRange() [1/6]

◆ StoredRange() [2/6]

◆ StoredRange() [3/6]

◆ StoredRange() [4/6]

◆ StoredRange() [5/6]

◆ StoredRange() [6/6]

◆ ~StoredRange()

Member Function Documentation

◆ begin()

◆ empty()

◆ end()

◆ first_idx()

◆ grainsize() [1/2]

◆ grainsize() [2/2]

◆ is_divisible()

◆ last_idx()

◆ reset() [1/2]

◆ reset() [2/2]

◆ size()

Member Data Documentation

◆ _begin

◆ _end

◆ _first

◆ _grainsize

◆ _last

◆ _objs