[For complete, up-to-date TBB information visit: http://www.ThreadingBuildingBlocks.org]
Summary
Template class that processes work items.
Syntax
template<typename Body>
class parallel_while;
Header
#include "tbb/parallel_while.h"
Description
A parallel_while<Body> performs parallel iteration over items. The processing to be performed on each item is defined by a function object of type Body. The items are specified in two ways:
1. A stream of items.
2. Additional items that are added while the stream is being processed.
Table 11 shows the requirements on the stream and body.
Table 11: parallel_while Requirements for Stream S and Body B
Pseudo-Signature
Semantics
bool S::pop_if_present( B::argument_type& item )
Get next stream item. parallel_while does not concurrently invoke the method on the same this.
B::operator()( B::argument_type& item ) const
Process item. parallel_while may concurrently invoke the operator for the same this but different item.
B::argument_type()
Default constructor
B::argument_type( const B::argument_type& )
Copy constructor
~B::argument_type()
Destructor
For example, a unary function object, as defined in Section 20.3 of the C++ standard, models the requirements for B. A concurrent_queue ( 4.2) models the requirements for S.
TIP: To achieve speedup, the grain size of B::operator() needs to be on the order of at least ~10,000 instructions. Otherwise, the internal overheads of parallel_while swamp the useful work. The parallelism in parallel_while is not scalable if all the items come from the input stream. To achieve scaling, design your algorithm such that method add often adds more than one piece of work.
Members
namespace tbb {
template<typename Body>
class parallel_while {
public:
parallel_while();
~parallel_while();
typedef typename Body::argument_type value_type;
template<typename Stream>
void run( Stream& stream, const Body& body );
void add( const value_type& item );
};
}
Effects
Construct a parallel_while that is not yet running.
Effects
Destroy a parallel_while.
Effects
Apply body to each item in stream and any other items that are added by method add. Terminates when both of the following conditions become true:
1. stream.pop_if_present returned false
2. body(x) returned for all items x generated from the stream or method add.
Requirements
Must be called from a call to body.operator() created by parallel_while. Otherwise, the termination semantics of method run are undefined.
Effects
Add item to collection of items to be processed.
[For complete, up-to-date TBB information visit: http://www.ThreadingBuildingBlocks.org]