Ocean::Worker Class Reference

This class implements a worker able to distribute function calls over different threads. More...

Inheritance diagram for Ocean::Worker:

Data Structures
class	WorkerThread
	This class implements a thread with an explicit external thread function. More...

Public Types
enum	LoadType : uint32_t {   TYPE_ONE_CORE , TYPE_HALF_CORES , TYPE_ALL_BUT_ONE_CORE , TYPE_ALL_CORES ,   TYPE_DOUBLE_CORES , TYPE_CUSTOM }
	Definition of CPU load types. More...
typedef Caller< void >	Function
	Definition of a worker function caller object for standard functions to be distributed. More...
typedef Caller< bool >	AbortableFunction
	Definition of a worker function caller object for abort functions. More...
typedef std::vector< Function >	Functions
	Definition of a vector holding worker functions. More...
typedef std::vector< unsigned int >	StartIndices
	Definition of a vector holding indices. More...

Public Member Functions
	Worker (const LoadType loadType=TYPE_ALL_CORES, const unsigned int maximalNumberCores=16u)
	Creates a new worker object. More...
	Worker (const unsigned int numberCores, const LoadType loadType)
	Creates a new worker object with a custom amount of worker threads. More...
	~Worker ()
	Destructs a worker object. More...
unsigned int	threads () const
	Returns the number of threads this worker uses. More...
bool	executeFunction (const Function &function, const unsigned int first, const unsigned int size, const unsigned int firstIndex=(unsigned int)(-1), const unsigned int sizeIndex=(unsigned int)(-1), const unsigned int minimalIterations=1u, const unsigned int threadIndex=(unsigned int)(-1))
	Executes a callback function separable by two function parameters. More...
bool	executeFunctions (const Functions &functions)
	Executes several callback functions concurrently. More...
bool	executeAbortableFunction (const AbortableFunction &abortableFunction, const unsigned int abortIndex, const unsigned int maximalExecutions=0u)
	Executes an abortable function on several CPU cores. More...
bool	executeSeparableAndAbortableFunction (const AbortableFunction &separableAbortableFunction, const unsigned int first, const unsigned int size, const unsigned int firstIndex, const unsigned int sizeIndex, const unsigned int abortIndex, const unsigned int minimalIterations=1)
	Executes an abortable and separable function on several CPU cores. More...
StartIndices	separation (const unsigned int first, const unsigned int size, const unsigned int minimalIterations=1u)
	Returns a separation this worker would apply to execute a distributable function. More...
	operator bool () const
	Returns whether this worker uses more than one thread to distribute a function. More...
	operator Worker * () const
	Explicit worker pointer operator. More...

Protected Types
typedef std::vector< WorkerThread * >	WorkerThreads
	Definition of a vector holding worker threads. More...

Protected Member Functions
	Worker (const Worker &worker)=delete
	Disabled copy constructor. More...
Worker &	operator= (const Worker &worker)=delete
	Disabled copy operator. More...

Protected Attributes
WorkerThreads	workerThreads_
	Worker threads. More...
Signals	signals_
	Worker signals determining whether all thread finished their work. More...
Lock	lock_
	Worker lock. More...

Detailed Description

This class implements a worker able to distribute function calls over different threads.

Thus, this worker object can be used to distribute complex operations to several CPU cores to speed up the entire computation significantly.
The worker provides several modes to distribute the computational load of a complex operation.
Function call my be made faster by using subsets of the entire data by individual CPU cores only.
Further, this worker supports abortable functions executing the same function several times and stops all other threads if the first function receives a valid result.
For more details several code examples are provided:

See also

executeFunction(), executeFunctions().

WorkerPool.

Member Typedef Documentation

AbortableFunction

typedef Caller<bool> Ocean::Worker::AbortableFunction

Definition of a worker function caller object for abort functions.

Function

typedef Caller<void> Ocean::Worker::Function

Definition of a worker function caller object for standard functions to be distributed.

Standard functions allow the computation using a subset of the entire data.

Functions

typedef std::vector<Function> Ocean::Worker::Functions

Definition of a vector holding worker functions.

StartIndices

typedef std::vector<unsigned int> Ocean::Worker::StartIndices

Definition of a vector holding indices.

WorkerThreads

typedef std::vector<WorkerThread*> Ocean::Worker::WorkerThreads

protected

Definition of a vector holding worker threads.

Member Enumeration Documentation

LoadType

enum Ocean::Worker::LoadType : uint32_t

Definition of CPU load types.

Enumerator
TYPE_ONE_CORE	One CPU core is used.
TYPE_HALF_CORES	Half of the CPU cores are used, minimum is one CPU core.
TYPE_ALL_BUT_ONE_CORE	All CPU cores but one, minimum is one CPU core.
TYPE_ALL_CORES	All CPU cores are used.
TYPE_DOUBLE_CORES	For each CPU core two thread are used.
TYPE_CUSTOM	A custom amount of CPU cores is used.

Constructor & Destructor Documentation

Worker() [1/3]

Ocean::Worker::Worker ( const LoadType  loadType = TYPE_ALL_CORES, const unsigned int  maximalNumberCores = 16u  )

explicit

Creates a new worker object.

The load type defines the number of cores to be used, however the worker will not address more than 'maximalNumberCores'.

Parameters

loadType	Load type used for this worker, must not be TYPE_CUSTOM
maximalNumberCores	The maximal number of cores to be used, with range [1, infinity)

Worker() [2/3]

Ocean::Worker::Worker	(	const unsigned int	numberCores,
		const LoadType	loadType
	)

Creates a new worker object with a custom amount of worker threads.

Parameters

numberCores	The number of threads to use, with range [1, infinity)
loadType	Must be TYPE_CUSTOM

~Worker()

Ocean::Worker::~Worker

(

)

Destructs a worker object.

Worker() [3/3]

Ocean::Worker::Worker ( const Worker &  worker )

protecteddelete

Disabled copy constructor.

Parameters

worker

Object which would be copied

Member Function Documentation

executeAbortableFunction()

bool Ocean::Worker::executeAbortableFunction	(	const AbortableFunction &	abortableFunction,
		const unsigned int	abortIndex,
		const unsigned int	maximalExecutions = 0u
	)

Executes an abortable function on several CPU cores.

The function must provide an abort parameter. The parameter is a pointer to a boolean state initialized with False.

Parameters

abortableFunction	Function supporting an abort state to terminate the function explicitly
abortIndex	Index of the abort parameter
maximalExecutions	Number of maximal CPU core executions

Returns

True, if one of the functions succeeded

executeFunction()

bool Ocean::Worker::executeFunction	(	const Function &	function,
		const unsigned int	first,
		const unsigned int	size,
		const unsigned int	firstIndex = (unsigned int)(-1),
		const unsigned int	sizeIndex = (unsigned int)(-1),
		const unsigned int	minimalIterations = 1u,
		const unsigned int	threadIndex = (unsigned int)(-1)
	)

Executes a callback function separable by two function parameters.

The first separable function parameter defines the start point.
The second separable function parameter defines the number of iterations for the specified start point.

This example shows how to use the worker object in combination with a distributable function:

void distributableFunction(unsigned char* data, const unsigned int firstByte, const unsigned int numberBytes)
{
    std::cout << "Function call handling bytes: " << firstByte << " up to " << firstByte + numberBytes - 1 << std::endl;
 
    // do something with the byte buffer
    // Beware: Change bytes inside the range [firstByte, firstByte + numberBytes - 1] only!
    // ...
}
 
void main()
{
    // worker object to execute the distributable function
    Worker worker;
 
    // create byte buffer
    unsigned char* data = new unsigned char[1024];
 
    // initialize buffer with something
    // ...
 
    // call the distributable function to do something with the buffer
    // start with element: 0
    // number of entire elements: 1024
    // the index of the function parameter 'firstByte' is 1 in the 'distributableFunction'
    // the index of the function parameter 'numberBytes' is 2 in the 'distributableFunction'
    worker.executeFunction(Worker::Function::createStatic(&distributeFunction, data, 0u, 0u), 0u, 1024u, 1u, 2u);
 
    // we can also skip the indices of the two function parameters 'firstByte' and 'numberBytes' as these order and position is like the default case (last two parameters while the number is the last parameter):
    worker.executeFunction(Worker::Function::createStatic(&distributeFunction, data, 0u, 0u), 0u, 1024u);
 
    // use the changed buffer
    // ...
 
    delete [] data;
}

Output for a CPU with 4 cores would be e.g. (the order of the output may vary):
Function call handling bytes: 0, 255
Function call handling bytes: 256, 511
Function call handling bytes: 512, 767
Function call handling bytes: 768, 1023

Parameters

function	Separable function to be execute
first	First function parameter
size	Size function parameter
firstIndex	Index of the worker function parameter receiving the start value, if -1 than the index will be set to the second last parameter, otherwise with range [0, function.parameters())
sizeIndex	Index of the worker function parameter receiving the number value, if -1 than the index will be set to the last parameter, otherwise with range [0, function.parameters())
minimalIterations	Minimal number of iterations assigned to one internal thread
threadIndex	Optional index of the worker function parameter receiving the index of the individual thread

Returns

True, if succeeded

executeFunctions()

bool Ocean::Worker::executeFunctions

(

const Functions &

functions

)

Executes several callback functions concurrently.

This example shows how to use the worker object in combination with several individual callback functions:

void function0(unsigned int value)
{
    std::cout << "Function0 call with value: " << value << std::endl;
 
    // do something here
    // ...
}
 
void function1(std::string value)
{
    std::cout << "Function1 call with value: " << value << std::endl;
 
    // do something here
    // ...
}
 
void main()
{
    // worker object to execute the distributable function
    Worker worker;
 
    // vector with callback functions
    Worker::Functions functions;
 
    // creating simple callback functions and adding them to the vector
    functions.push_back(Worker::Function::createStatic(&function0, 9));
    functions.push_back(Worker::Function::createStatic(&function0, 101));
    functions.push_back(Worker::Function::createStatic(&function1, std::string("hallo"));
    functions.push_back(Worker::Function::createStatic(&function1, std::string("world"));
 
    // call the callback functions concurrently
    worker.executeFunctions(functions);
 
    // do something
}

Output (the order of the output may vary):
Function0 call with value: 9
Function1 call with value: world
Function0 call with value: 101
Function1 call with value: hallo

Parameters

functions

Callback function to execute

Returns

True, if succeeded

executeSeparableAndAbortableFunction()

bool Ocean::Worker::executeSeparableAndAbortableFunction	(	const AbortableFunction &	separableAbortableFunction,
		const unsigned int	first,
		const unsigned int	size,
		const unsigned int	firstIndex,
		const unsigned int	sizeIndex,
		const unsigned int	abortIndex,
		const unsigned int	minimalIterations = 1
	)

Executes an abortable and separable function on several CPU cores.

The function must be separable by two function parameters and must provide an abort parameter allowing to stop the function execution immediately.

Parameters

separableAbortableFunction	Function supporting an separation and aborting
first	The first function parameter
size	The size function parameter
firstIndex	Index of the worker function parameter receiving the start value
sizeIndex	Index of the worker function parameter receiving the number value
abortIndex	Index of the abort parameter
minimalIterations	Minimal number of iterations assigned to one internal thread

Returns

True, if one of the abortable functions succeeded

operator bool()

Ocean::Worker::operator bool ( ) const

inlineexplicit

Returns whether this worker uses more than one thread to distribute a function.

Returns

True, if so

operator Worker *()

Ocean::Worker::operator Worker * ( ) const

inline

Explicit worker pointer operator.

Returns

Worker operator

operator=()

Worker& Ocean::Worker::operator= ( const Worker &  worker )

protecteddelete

Disabled copy operator.

Parameters

worker

Object which would be copied

Returns

Reference to this object

separation()

StartIndices Ocean::Worker::separation	(	const unsigned int	first,
		const unsigned int	size,
		const unsigned int	minimalIterations = 1u
	)

Returns a separation this worker would apply to execute a distributable function.

Parameters

first	The first function parameter
size	The size function parameter
minimalIterations	Minimal number of iterations assigned to one internal thread

Returns

Resulting separation (indices of the start points)

threads()

unsigned int Ocean::Worker::threads

(

)

const

Returns the number of threads this worker uses.

Returns

Number of used threads

Field Documentation

lock_

Lock Ocean::Worker::lock_

protected

Worker lock.

signals_

Signals Ocean::Worker::signals_

protected

Worker signals determining whether all thread finished their work.

workerThreads_

WorkerThreads Ocean::Worker::workerThreads_

protected

Worker threads.

---

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

• Worker.h