Oyranos Color Management System API - Version 0.9.6
Data Structures | Typedefs | Functions | Variables
Threading

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)
 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 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...
 
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...
 
 oyJob_s::oyJob_New
 Allocate a new oyJob_s object. More...
 
 oyJob_s::oyJob_Release
 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 new Jobs. 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" 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.

Typedef Documentation

oyJob_Add_f

Add one unique oyJob_s to the job qeue.

Version
Oyranos: 0.9.6
Date
2016/05/01
Since
2016/05/01 (Oyranos: 0.9.6)
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

Progress callback for parallel job processing.

Version
Oyranos: 0.9.6
Date
2016/05/02
Since
2014/01/27 (Oyranos: 0.9.5)
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

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)

Function Documentation

oyJob_New

Allocate a new oyJob_s object.

A object argument is ignored.

Version
Oyranos: 0.9.6
Date
2016/05/02
Since
2016/05/02 (Oyranos: 0.9.6)
Examples:
image_display.cpp.
oyJob_Release

Deallocate a oyJob_s object.

Version
Oyranos: 0.9.6
Date
2016/05/02
Since
2016/05/02 (Oyranos: 0.9.6)
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.

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)
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_f oyJob_Add = oyJob_AddInit

Add one unique oyJob_s to the job qeue.

See Also
oyJob_Add_f
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().

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_f oyJobResult = oyJobResultInit

Poll for new Jobs.

See Also
oyJobResult_f
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_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().