Threading
Description: C source code API documentation for the Oyranos project.
Keywords: Oyranos,Color Management,Color Management,ICC,CMS,C,doxygen,API,documentation

| Oyranos Color Management System API - Version 0.9.6

Data Structures | Typedefs | Functions | Variables
Threading
Miscellaneous

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

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

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.

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)

## Function Documentation

## ◆ oyJob_New()

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)

## ◆ oyJob_Release()

oyJob_Release

Deallocate a oyJob_s object.

Version
  Oyranos: 0.9.6

Date
  2016/05/02

Since
  2016/05/02 (Oyranos: 0.9.6)

## ◆ 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.

## ◆ 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)

## ◆ 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

Version
  Oyranos: 0.9.6

Since
  2016/05/01 (Oyranos: 0.9.6)

Date
  2016/05/01

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 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

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().