Asynchron processing support. More...

Collaboration diagram for Threading:

Data Structures
struct	oyJob_s
	Asynchron job ticket. More...

Typedefs
typedef int(*	oyJob_Add_f) (oyJob_s **job, int finished, int flags)
	Add one unique oyJob_s to the job qeue. More...

typedef int(*	oyJob_Get_f) (oyJob_s **job, int finished)
	Get one unique oyJob_s from the job qeue. More...

typedef int(*	oyMsg_Add_f) (oyJob_s job, double progress_zero_till_one, char *status_text)
	Add one unique message from the message qeue. More...

typedef void(*	oyJobResult_f) (void)
	Poll for new Jobs. More...

typedef int(*	oyThreadId_f) (void)
	Get one unique thread ID. More...

typedef void(*	oyJobCallback_f) (double progress_zero_till_one, char status_text, int thread_id_, int job_id, oyStruct_s cb_progress_context)
	Progress callback for parallel job processing. More...

Functions
void	oyThreadLockingSet (oyStruct_LockCreate_f createLockFunc, oyLockRelease_f releaseLockFunc, oyLock_f lockFunc, oyUnLock_f unlockFunc)
	set locking functions for threaded applications More...

void	oyThreadLockingReset ()
	unset locking functions for threaded applications More...

int	oyThreadLockingReady (void)
	tell if thread locking is ready More...

void	oyJob_s::oyJobHandlingSet (oyJob_Add_f jadd, oyJob_Get_f jget, oyMsg_Add_f madd, oyJobResult_f result, const char *nick)
	Initialise the oyJob_s APIs. More...

void	oyJob_s::oyJobHandlingReset ()
	Reset the oyJob_s APIs. More...

oyJob_s *	oyJob_s::oyJob_New (oyObject_s object OY_UNUSED)
	Allocate a new oyJob_s object. More...

void	oyJob_s::oyJob_Release (oyJob_s **job)
	Deallocate a oyJob_s object. More...

Variables
oyJob_Add_f	oyJob_s::oyJob_Add = oyJob_AddInit
	Add one unique oyJob_s to the job qeue. More...

oyJob_Get_f	oyJob_s::oyJob_Get = oyJob_GetInit
	Get one unique oyJob_s from the job qeue. More...

oyMsg_Add_f	oyJob_s::oyMsg_Add = oyMsg_AddInit
	Add one unique message from the message qeue. More...

oyJobResult_f	oyJob_s::oyJobResult = oyJobResultInit
	Poll for messages and finished jobs. More...

oyThreadId_f	oyThreadId = oyThreadIdInit
	Get one unique thread Id. More...

Detailed Description

Asynchron processing support.

Concept

Threading support in Oyranos is kept intentionally simple. Object level locking is available. Eigther avoid Oyranos locking by encapsulating it into a own locking model. Or provide locking functions in oyThreadLockingSet(), which can detect recursive lock conditions. Recursive locks might not be a problem with POSIX systems and pthreads PTHREAD_MUTEX_RECURSIVE.

Job handling is more complex. A version is provided in the "trds" module and will be initialised by default during first use of the APIs. This version used a threading model as is available during compilation. In case you want a own threading model you can provide it through oyJobHandlingSet().

Why asynchronous processing?

Some expensive workload is good to load off to a background job and continue in the foreground for non interupted user interaction. E.g. the user should be able to continue interacting with the image/movie, even while changed options need computing of the current DAG contexts.

Why threading inside Oyranos?

The background jobs tend to be related to tasks inside the Oyranos DAG and can not easily be handled outside the DAG. For instance it is not easy to replace a expensive DAG while performing a expensive option change - big image or movie + switching on/off proofing/effects.

Why a modular approach?

Threading models can very easily conflict and linking can become a night mare. Thus threading from "trds" plug-in must be replaceable on the descretion of users.

Initialisation

Call oyThreadLockingSet() in order to use own thread locking functions. Call oyJobHandlingSet() to replace by own Job handling functions. The functions must be used before any call to Oyranos.

API usage

Adding Jobs

A oyJob_New() creates a new oyJob_s object which can be added to the job qeue by oyJob_Add(). Job creation and Job adding belongs to the managing thread. Calling oyJob_Add() for the first time in the process initialises the API's and starts the worker threads. oyJob_s::work() is called from inside the worker thread.

Processing Jobs

oyJob_s::work() does the asynchron oyJob_s::context processing. It can add messages with oyMsg_Add() to the message qeue. After returning from oyJob_s::work() the job object is placed back into the job qeue and marked as done (finished == 1) by the thread handling plug-in.

Getting Results

Calling oyJobResult() in managing thread, usually the main GUI thread, allows to obtain progress status from the Oyranos worker threads. jobPrintfCallback() is the default message callback and just does printing a status information, which were previously add inside the oyJob_s::work() inside the worker thread with oyMsg_Add(). The oyJob_s object, including the processed data, is placed into the job qeue after oyJob_s::work() returned. To access the oyJob_s use the oyJob_s::finish() callback. oyJobResult() is as well responsible to call oyJob_s::finish() from the managing/UI thread for that.

Debugging

See Environment Variables .

Typedef Documentation

◆ oyJob_Add_f

oyJob_Add_f

Add one unique oyJob_s to the job qeue.

Version: Oyranos: 0.9.7

Date: 2017/09/22

Since: 2016/05/01 (Oyranos: 0.9.6)

◆ oyJob_Get_f

oyJob_Get_f

Get one unique oyJob_s from the job qeue.

Version: Oyranos: 0.9.6

Date: 2016/05/01

Since: 2016/05/01 (Oyranos: 0.9.6)

◆ oyJobCallback_f

oyJobCallback_f

Progress callback for parallel job processing.

Parameters

progress_zero_till_one	will be called by the work thread with 0.0 before start of oyJob_s::work() and after with 1.0 between oyMsg_Add() can be used inside oyJob_s::work() to add more fine grained status info
status_text	textual description of the work progress
thread_id_	work thread info
job_id	id of the job
cb_progress_context	GUI context; e.g. gauge/progress bar ... (unused)

Version: Oyranos: 0.9.6

Date: 2016/05/02

Since: 2014/01/27 (Oyranos: 0.9.5)

◆ oyJobResult_f

oyJobResult_f

Poll for new Jobs.

Version: Oyranos: 0.9.6

Date: 2016/05/01

Since: 2016/05/01 (Oyranos: 0.9.6)

◆ oyMsg_Add_f

oyMsg_Add_f

Add one unique message from the message qeue.

Version: Oyranos: 0.9.6

Date: 2016/05/01

Since: 2016/05/01 (Oyranos: 0.9.6)

◆ oyThreadId_f

oyThreadId_f

Get one unique thread ID.

Version: Oyranos: 0.9.7

Date: 2019/09/22

Since: 2019/09/22 (Oyranos: 0.9.7)

Function Documentation

◆ oyJob_New()

oyJob_s * oyJob_New ( oyObject_s object OY_UNUSED )

Allocate a new oyJob_s object.

Function oyJob_New

A object argument is ignored.

Version: Oyranos: 0.9.6

Date: 2016/05/02

Since: 2016/05/02 (Oyranos: 0.9.6)

◆ oyJob_Release()

void oyJob_Release ( oyJob_s ** job )

Deallocate a oyJob_s object.

Function oyJob_Release

Version: Oyranos: 0.9.6

Date: 2016/05/02

Since: 2016/05/02 (Oyranos: 0.9.6)

References oyOBJECT_JOB_S, and oyJob_s::type_.

◆ oyJobHandlingReset()

void oyJobHandlingReset ( )

Reset the oyJob_s APIs.

Clean all functions for new initialisation. Otherwise the behaviour is undefined.

Version: Oyranos: 0.9.7

Since: 2020/07/09 (Oyranos: 0.9.7)

Date: 2020/07/09

References oyJob_s::oyJobHandlingSet().

◆ oyJobHandlingSet()

void oyJobHandlingSet	(	oyJob_Add_f	jadd,
		oyJob_Get_f	jget,
		oyMsg_Add_f	madd,
		oyJobResult_f	result,
		const char *	nick
	)

Initialise the oyJob_s APIs.

Be careful to set the APIs only before any call to the oyJob_s functions. Otherwise the behaviour is undefined.

Version: Oyranos: 0.9.6

Since: 2016/05/01 (Oyranos: 0.9.6)

Date: 2016/05/01

References oyJob_s::oyJob_Add, oyJob_s::oyJob_Get, oyJob_s::oyJobResult, and oyJob_s::oyMsg_Add.

Referenced by oyJob_s::oyJobHandlingReset().

◆ oyThreadLockingReady()

int oyThreadLockingReady ( void )

tell if thread locking is ready

Version: Oyranos: 0.9.5

Date: 2014/02/04

Since: 2014/02/04 (Oyranos: 0.9.5)

◆ oyThreadLockingReset()

void oyThreadLockingReset ( )

unset locking functions for threaded applications

Function: oyThreadLockingReset

Use this after threads ended to remove resources.

Version: Oyranos: 0.9.7

Since: 2020/07/07 (Oyranos: 0.9.7)

Date: 2020/07/07

◆ oyThreadLockingSet()

void oyThreadLockingSet	(	oyStruct_LockCreate_f	createLockFunc,
		oyLockRelease_f	releaseLockFunc,
		oyLock_f	lockFunc,
		oyUnLock_f	unlockFunc
	)

set locking functions for threaded applications

Function: oyThreadLockingSet

Since: Oyranos: version 0.1.8

Date: 14 january 2008 (API 0.1.8)

Variable Documentation

◆ oyJob_Add

oyJob_Add_f oyJob_Add = oyJob_AddInit

Add one unique oyJob_s to the job qeue.

See also: oyJob_Add_f

Parameters

job	the job object
finished	mark the job in the queue 0 - to be processed; work funtion was not yet called 1 - finished processing; work function was called inside the worker thread; ready for getting with oyJob_Get()
flags	hint on how to process the job oyJOB_ADD_PERSISTENT_JOB - suggest to add a new thread as the job may run over the whole process live time; typical for a asynchron observer

Returns: the job ID

Version: Oyranos: 0.9.7

Date: 2017/09/22

Since: 2016/05/01 (Oyranos: 0.9.6)

Referenced by oyJob_s::oyJobHandlingSet().

◆ oyJob_Get

oyJob_Get_f oyJob_Get = oyJob_GetInit

Get one unique oyJob_s from the job qeue.

See also: oyJob_Get_f

Version: Oyranos: 0.9.6

Since: 2016/05/01 (Oyranos: 0.9.6)

Date: 2016/05/01

Referenced by oyJob_s::oyJobHandlingSet().

◆ oyJobResult

oyJobResult_f oyJobResult = oyJobResultInit

Poll for messages and finished jobs.

See also: oyJobResult_f

The function does two things. It calls oyJob_s::cb_progress() from a filled message qeue. And it takes jobs out of the job qeue, which are marked as finalised. oyJob_s::finish() is optionally called. After the oyJob_s::finish() callback the job is released.

The function is usually called from the managing-and main UI thread.

Version: Oyranos: 0.9.6

Since: 2016/05/01 (Oyranos: 0.9.6)

Date: 2016/05/01

Examples:: image_display.cpp.

Referenced by oyJob_s::oyJobHandlingSet().

◆ oyMsg_Add

oyMsg_Add_f oyMsg_Add = oyMsg_AddInit

Add one unique message from the message qeue.

See also: oyMsg_Add_f

Version: Oyranos: 0.9.6

Since: 2016/05/01 (Oyranos: 0.9.6)

Date: 2016/05/01

Referenced by oyJob_s::oyJobHandlingSet().

◆ oyThreadId

oyThreadId_f oyThreadId = oyThreadIdInit

Get one unique thread Id.

See also: oyThreadId_f

Version: Oyranos: 0.9.7

Date: 2019/09/22

Since: 2019/09/22 (Oyranos: 0.9.7)

Data Structures

Typedefs

Functions

Variables

Detailed Description

Concept

Why asynchronous processing?

Why threading inside Oyranos?

Why a modular approach?

Initialisation

API usage

Adding Jobs

Processing Jobs

Getting Results

Debugging

Typedef Documentation

◆ oyJob_Add_f

◆ oyJob_Get_f

◆ oyJobCallback_f

◆ oyJobResult_f

◆ oyMsg_Add_f

◆ oyThreadId_f

Function Documentation

◆ oyJob_New()

◆ oyJob_Release()

◆ oyJobHandlingReset()

◆ oyJobHandlingSet()

◆ oyThreadLockingReady()

◆ oyThreadLockingReset()

◆ oyThreadLockingSet()

Variable Documentation

◆ oyJob_Add

◆ oyJob_Get

◆ oyJobResult

◆ oyMsg_Add

◆ oyThreadId