parallel_while Template Class

Summary

Template class that processes work items.

Tip

This class is deprecated. Use parallel_do (4.7) instead.

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:

Table 44 shows the requirements on the stream and body.

Table 44: 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 (5.5) models the requirements for S.

Tip

To achieve speedup, the grainsize 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 );
 };
 }
The following table provides additional information on the members of this template class.
Member Description
parallel_while<Body>()

Constructs a parallel_while that is not yet running.

~parallel_while<Body>()

Destroys a parallel_while.

Template <typename Stream> void run( Stream& stream, const Body& body )

Applies 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:

  • stream.pop_if_present returned false.

  • body(x) returned for all items x generated from the stream or method add.

void add( const value_type& item )

Requirements: Must be called from a call to body.operator() created by parallel_while. Otherwise, the termination semantics of method run are undefined.

Effects: Adds item to collection of items to be processed.