Description

template<class DependencyGraph, class Functor>
class Sawyer::ThreadWorkers< DependencyGraph, Functor >

Work list with dependencies.

This class takes a graph of tasks. The vertices are the tasks that need to be worked on, and an edge from vertex a to vertex b means work on a depends on b having been completed. Vertices that participate in a cycle cannot be worked on since there is no way to resolve their dependencies; in this case, as much work as possible is performed.

See also, the workInParallel function which is less typing since template parameters are inferred.

Definition at line 32 of file ThreadWorkers.h.

#include <ThreadWorkers.h>

Public Member Functions
	ThreadWorkers ()
	Default constructor. More...

	ThreadWorkers (const DependencyGraph &dependencies, size_t nWorkers, Functor functor)
	Constructor that synchronously runs the work. More...

	~ThreadWorkers ()
	Destructor. More...

void	start (const DependencyGraph &dependencies, size_t nWorkers, Functor functor)
	Start workers and return. More...

void	wait ()
	Wait for work to complete. More...

template<class Rep , class Period >
bool	tryWaitFor (const boost::chrono::duration< Rep, Period > &relTime)
	Wait for work to complete. More...

void	run (const DependencyGraph &dependencies, size_t nWorkers, Functor functor)
	Synchronously processes tasks. More...

bool	isFinished ()
	Test whether all possible work is finished. More...

size_t	nStarted ()
	Number of tasks that have started. More...

size_t	nFinished ()
	Number of tasks that have completed. More...

std::set< size_t >	runningTasks ()
	Tasks currently running. More...

std::pair< size_t, size_t >	nWorkers ()
	Number of worker threads. More...

Constructor & Destructor Documentation

◆ ThreadWorkers() [1/2]

template<class DependencyGraph , class Functor >

Sawyer::ThreadWorkers< DependencyGraph, Functor >::ThreadWorkers ( )

inline

Default constructor.

This constructor initializes the object but does not start any worker threads. Each object can perform work a single time, which is done by calling run (synchronous) or start and wait (asynchronous).

Definition at line 52 of file ThreadWorkers.h.

◆ ThreadWorkers() [2/2]

template<class DependencyGraph , class Functor >

Sawyer::ThreadWorkers< DependencyGraph, Functor >::ThreadWorkers	(	const DependencyGraph &	dependencies,
		size_t	nWorkers,
		Functor	functor
	)

inline

Constructor that synchronously runs the work.

This constructor creates up to the specified number of worker threads to run the work described in the dependencies (at least one thread, but not more than the number of vertices in the graph). If nWorkers is zero then the system's hadware concurrency is used. If the dependency graph contains a cycle then as much work as possible is performed and then a ContainsCycle exception is thrown.

The dependency graph is copied into this class so that the class can modify it as tasks are completed. The functor can be a class with operator(), a function pointer, or a lambda expression. If a class is used, it must be copyable and each worker thread will be given its own copy. The functor is invoked with two arguments: the ID number of the task being processed, and a reference to a copy of the task (vertex value) in the dependency graph. The ID number is the vertex ID number in the dependencies graph.

The constructor does not return until all possible non-cyclic work has been completed. This object can only perform work a single time.

Definition at line 71 of file ThreadWorkers.h.

References Sawyer::ThreadWorkers< DependencyGraph, Functor >::nWorkers(), and Sawyer::ThreadWorkers< DependencyGraph, Functor >::run().

Here is the call graph for this function:

◆ ~ThreadWorkers()

template<class DependencyGraph , class Functor >

Sawyer::ThreadWorkers< DependencyGraph, Functor >::~ThreadWorkers ( )

inline

Destructor.

The destructor waits for all possible non-cyclic work to complete before returning.

Definition at line 85 of file ThreadWorkers.h.

References Sawyer::ThreadWorkers< DependencyGraph, Functor >::wait().

Here is the call graph for this function:

Member Function Documentation

◆ start()

template<class DependencyGraph , class Functor >

void Sawyer::ThreadWorkers< DependencyGraph, Functor >::start	(	const DependencyGraph &	dependencies,
		size_t	nWorkers,
		Functor	functor
	)

inline

Start workers and return.

This method saves a copy of the dependencies, initializes a work list, and starts worker threads. The vertices of the dependency graph are the tasks to be performed by the workers and the edges represent dependencies between the tasks. An edge from vertex a to vertex b means that task a cannot start until work on task b has finished.

The tasks in dependencies are processed by up to nWorkers threads created by this method and destroyed when work is complete. This method creates at least one thread (if there's any work), but never more threads than the total amount of work. If nWorkers is zero then the system's hardware concurrency is used. It returns as soon as those workers are created.

Each object can perform work only a single time.

Definition at line 103 of file ThreadWorkers.h.

References Sawyer::ThreadWorkers< DependencyGraph, Functor >::nWorkers().

Referenced by Sawyer::ThreadWorkers< DependencyGraph, Functor >::run(), and Sawyer::workInParallel().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ wait()

template<class DependencyGraph , class Functor >

void Sawyer::ThreadWorkers< DependencyGraph, Functor >::wait ( )

inline

Wait for work to complete.

This call blocks until all possible non-cyclic work is completed. If no work has started yet then it returns immediately.

Definition at line 122 of file ThreadWorkers.h.

Referenced by Sawyer::ThreadWorkers< DependencyGraph, Functor >::run(), and Sawyer::ThreadWorkers< DependencyGraph, Functor >::~ThreadWorkers().

Here is the caller graph for this function:

◆ tryWaitFor()

template<class DependencyGraph , class Functor >

template<class Rep , class Period >

bool Sawyer::ThreadWorkers< DependencyGraph, Functor >::tryWaitFor ( const boost::chrono::duration< Rep, Period > & relTime )

inline

Wait for work to complete.

Waits for up to the specified amount of time for work to complete. Returns true if no work has been started, or all work has completed within the time period. Returns false if a timeout occurred while waiting for work to complete.

Definition at line 143 of file ThreadWorkers.h.

Referenced by Sawyer::workInParallel().

Here is the caller graph for this function:

◆ run()

template<class DependencyGraph , class Functor >

void Sawyer::ThreadWorkers< DependencyGraph, Functor >::run	(	const DependencyGraph &	dependencies,
		size_t	nWorkers,
		Functor	functor
	)

inline

Synchronously processes tasks.

This is simply a wrapper around start and wait. It performs work synchronously, returning only after all possible work has completed. If the dependency graph contained cycles then a ContainsCycle exception is thrown after all possible non-cyclic work is finished.

Definition at line 168 of file ThreadWorkers.h.

References Sawyer::ThreadWorkers< DependencyGraph, Functor >::nWorkers(), Sawyer::ThreadWorkers< DependencyGraph, Functor >::start(), and Sawyer::ThreadWorkers< DependencyGraph, Functor >::wait().

Referenced by Sawyer::ThreadWorkers< DependencyGraph, Functor >::ThreadWorkers().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isFinished()

template<class DependencyGraph , class Functor >

bool Sawyer::ThreadWorkers< DependencyGraph, Functor >::isFinished ( )

inline

Test whether all possible work is finished.

Returns false if work is ongoing, true if all possible non-cyclic work is finished or no work was ever started.

Definition at line 176 of file ThreadWorkers.h.

◆ nStarted()

template<class DependencyGraph , class Functor >

size_t Sawyer::ThreadWorkers< DependencyGraph, Functor >::nStarted ( )

inline

Number of tasks that have started.

This is the number of tasks that have been started, some of which may have completed already. Although this function is thread-safe, the returned data might be out of date by time the caller accesses it.

Definition at line 185 of file ThreadWorkers.h.

◆ nFinished()

template<class DependencyGraph , class Functor >

size_t Sawyer::ThreadWorkers< DependencyGraph, Functor >::nFinished ( )

inline

Number of tasks that have completed.

Although this function is thread-safe, the returned data might be out of date by time the caller accesses it.

Definition at line 193 of file ThreadWorkers.h.

Referenced by Sawyer::workInParallel().

Here is the caller graph for this function:

◆ runningTasks()

template<class DependencyGraph , class Functor >

std::set<size_t> Sawyer::ThreadWorkers< DependencyGraph, Functor >::runningTasks ( )

inline

Tasks currently running.

Returns the set of tasks (dependency graph vertex IDs) that are currently running. Although this function is thread-safe, the returned data might be out of date by time the caller accesses it.

Definition at line 202 of file ThreadWorkers.h.

Referenced by Sawyer::workInParallel().

Here is the caller graph for this function:

◆ nWorkers()

template<class DependencyGraph , class Functor >

std::pair<size_t, size_t> Sawyer::ThreadWorkers< DependencyGraph, Functor >::nWorkers ( )

inline

Number of worker threads.

Returns a pair of numbers. The first is the total number of worker threads that are allocated, and the second is the number of threads that are busy working. The second number will never be larger than the first.

Definition at line 211 of file ThreadWorkers.h.

Referenced by Sawyer::ThreadWorkers< DependencyGraph, Functor >::run(), Sawyer::ThreadWorkers< DependencyGraph, Functor >::start(), and Sawyer::ThreadWorkers< DependencyGraph, Functor >::ThreadWorkers().

Here is the caller graph for this function: