parallel_while Template Class

Summary

Template class that processes work items.

Tip

This class is deprecated. Use parallel_do 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:

  • A stream of items.

  • Additional items that are added while the stream is being processed.

The following table shows the requirements on the stream and body.

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 stream object.

B::operator()( B::argument_type& item ) const

Process an item. parallel_while may concurrently invoke the operator for the same body object but different item.

B::argument_type()

Default constructor.

B::argument_type( const B::argument_type& )

Copy constructor.

~B::argument_type()

Destructor.

Tip

To achieve speedup, B::operator() should consist 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.

For more complete information about compiler optimizations, see our Optimization Notice.