thread.c File Reference
`#include <assert.h>`
`#include "opj_includes.h"`

## Data Structures

struct | opj_tls_key_val_t
struct | opj_tls_t
struct | opj_worker_thread_job_t
struct | opj_worker_thread_t
struct | opj_job_list_t
struct | opj_worker_thread_list_t
struct | opj_thread_pool_t

## Typedefs

typedef struct opj_job_list_t | opj_job_list_t
typedef struct opj_worker_thread_list_t | opj_worker_thread_list_t

## Enumerations

enum | opj_worker_thread_state { OPJWTS_OK , OPJWTS_STOP , OPJWTS_ERROR }

## Functions

OPJ_BOOL OPJ_CALLCONV | opj_has_thread_support (void)
| Returns if the library is built with thread support.
int OPJ_CALLCONV | opj_get_num_cpus (void)
| Return the number of virtual CPUs.
opj_mutex_t * | opj_mutex_create (void)
| Creates a mutex.
void | opj_mutex_lock (opj_mutex_t *mutex)
| Lock/acquire the mutex.
void | opj_mutex_unlock (opj_mutex_t *mutex)
| Unlock/release the mutex.
void | opj_mutex_destroy (opj_mutex_t *mutex)
| Destroy a mutex.
opj_cond_t * | opj_cond_create (void)
| Creates a condition.
void | opj_cond_wait (opj_cond_t *cond, opj_mutex_t *mutex)
| Wait for the condition to be signaled.
void | opj_cond_signal (opj_cond_t *cond)
| Signal waiting threads on a condition.
void | opj_cond_destroy (opj_cond_t *cond)
| Destroy a condition.
opj_thread_t * | opj_thread_create (opj_thread_fn thread_fn, void *user_data)
| Creates a new thread.
void | opj_thread_join (opj_thread_t *thread)
| Wait for a thread to be finished and release associated resources to the thread handle.
static opj_tls_t * | opj_tls_new (void)
static void | opj_tls_destroy (opj_tls_t *tls)
void * | opj_tls_get (opj_tls_t *tls, int key)
| Get a thread local value corresponding to the provided key.
OPJ_BOOL | opj_tls_set (opj_tls_t *tls, int key, void *value, opj_tls_free_func opj_free_func)
| Set a thread local value corresponding to the provided key.
static OPJ_BOOL | opj_thread_pool_setup (opj_thread_pool_t *tp, int num_threads)
static opj_worker_thread_job_t * | opj_thread_pool_get_next_job (opj_thread_pool_t *tp, opj_worker_thread_t *worker_thread, OPJ_BOOL signal_job_finished)
opj_thread_pool_t * | opj_thread_pool_create (int num_threads)
| Create a new thread pool.
static void | opj_worker_thread_function (void *user_data)
OPJ_BOOL | opj_thread_pool_submit_job (opj_thread_pool_t *tp, opj_job_fn job_fn, void *user_data)
| Submit a new job to be run by one of the thread in the thread pool.
void | opj_thread_pool_wait_completion (opj_thread_pool_t *tp, int max_remaining_jobs)
| Wait that no more than max_remaining_jobs jobs are remaining in the queue of the thread pool.
int | opj_thread_pool_get_thread_count (opj_thread_pool_t *tp)
| Return the number of threads associated with the thread pool.
void | opj_thread_pool_destroy (opj_thread_pool_t *tp)
| Destroy a thread pool.

## Typedef Documentation

## opj_job_list_t

typedef struct opj_job_list_t opj_job_list_t

## opj_worker_thread_list_t

typedef struct opj_worker_thread_list_t opj_worker_thread_list_t

## Enumeration Type Documentation

## opj_worker_thread_state

enum opj_worker_thread_state

Enumerator
OPJWTS_OK |
OPJWTS_STOP |
OPJWTS_ERROR |

## Function Documentation

## opj_cond_create()

opj_cond_t * opj_cond_create | ( | void |  | ) |

Creates a condition.

Returns
  the condition or NULL in case of error (can for example happen if the library is built without thread support)

Referenced by opj_thread_pool_setup().

## opj_cond_destroy()

void opj_cond_destroy | ( | opj_cond_t * | cond | ) |

Destroy a condition.

Parameters

  cond | the condition to destroy.

Referenced by opj_thread_pool_destroy(), and opj_thread_pool_setup().

## opj_cond_signal()

void opj_cond_signal | ( | opj_cond_t * | cond | ) |

Signal waiting threads on a condition.

One of the thread waiting with opj_cond_wait() will be waken up. It is strongly advised that this call is done with the mutex that is used by opj_cond_wait(), in a acquired state.

Parameters

  cond | the condition to signal.

Referenced by opj_thread_pool_destroy(), opj_thread_pool_get_next_job(), and opj_thread_pool_submit_job().

## opj_cond_wait()

void opj_cond_wait | ( | opj_cond_t * | cond,
|  | opj_mutex_t * | mutex
| ) |  |

Wait for the condition to be signaled.

The semantics is the same as the POSIX pthread_cond_wait. The provided mutex must be acquired before calling this function, and released afterwards. The mutex will be released by this function while it must wait for the condition and reacquired afterwards. In some particular situations, the function might return even if the condition is not signaled with opj_cond_signal(), hence the need to check with an application level mechanism.

Waiting thread :

opj_mutex_lock(mutex);
while( !some_application_level_condition )
{
opj_cond_wait(cond, mutex);
}
opj_mutex_unlock(mutex);
opj_cond_wait
void opj_cond_wait(opj_cond_t *cond, opj_mutex_t *mutex)
Wait for the condition to be signaled.
Definition thread.c:468
opj_mutex_lock
void opj_mutex_lock(opj_mutex_t *mutex)
Lock/acquire the mutex.
Definition thread.c:448
opj_mutex_unlock
void opj_mutex_unlock(opj_mutex_t *mutex)
Unlock/release the mutex.
Definition thread.c:453

Signaling thread :

opj_mutex_lock(mutex);
some_application_level_condition = TRUE;
opj_cond_signal(cond);
opj_mutex_unlock(mutex);
opj_cond_signal
void opj_cond_signal(opj_cond_t *cond)
Signal waiting threads on a condition.
Definition thread.c:474

Parameters

  cond | the condition to wait.
  mutex | the mutex (in acquired state before calling this function)

Referenced by opj_thread_pool_get_next_job(), opj_thread_pool_setup(), opj_thread_pool_submit_job(), and opj_thread_pool_wait_completion().

## opj_get_num_cpus()

int OPJ_CALLCONV opj_get_num_cpus | ( | void |  | ) |

Return the number of virtual CPUs.

Referenced by opj_j2k_get_default_thread_count().

## opj_has_thread_support()

OPJ_BOOL OPJ_CALLCONV opj_has_thread_support | ( | void |  | ) |

Returns if the library is built with thread support.

OPJ_TRUE if mutex, condition, thread, thread pool are available.

References OPJ_FALSE.

Referenced by opj_j2k_get_default_thread_count(), and opj_j2k_set_threads().

## opj_mutex_create()

opj_mutex_t * opj_mutex_create | ( | void |  | ) |

Creates a mutex.

Returns
  the mutex or NULL in case of error (can for example happen if the library is built without thread support)

Referenced by opj_t1_encode_cblks(), opj_tcd_t1_decode(), opj_thread_pool_create(), and opj_thread_pool_setup().

## opj_mutex_destroy()

void opj_mutex_destroy | ( | opj_mutex_t * | mutex | ) |

Destroy a mutex.

Parameters

  mutex | the mutex to destroy.

Referenced by opj_t1_encode_cblks(), opj_tcd_t1_decode(), opj_thread_pool_destroy(), and opj_thread_pool_setup().

## opj_mutex_lock()

void opj_mutex_lock | ( | opj_mutex_t * | mutex | ) |

Lock/acquire the mutex.

Parameters

  mutex | the mutex to acquire.

Referenced by opj_t1_cblk_encode_processor(), opj_t1_clbl_decode_processor(), opj_t1_decode_cblk(), opj_t1_ht_decode_cblk(), opj_thread_pool_destroy(), opj_thread_pool_get_next_job(), opj_thread_pool_setup(), opj_thread_pool_submit_job(), and opj_thread_pool_wait_completion().

## opj_mutex_unlock()

void opj_mutex_unlock | ( | opj_mutex_t * | mutex | ) |

Unlock/release the mutex.

Parameters

  mutex | the mutex to release.

Referenced by opj_t1_cblk_encode_processor(), opj_t1_clbl_decode_processor(), opj_t1_decode_cblk(), opj_t1_ht_decode_cblk(), opj_thread_pool_destroy(), opj_thread_pool_get_next_job(), opj_thread_pool_setup(), opj_thread_pool_submit_job(), and opj_thread_pool_wait_completion().

## opj_thread_create()

opj_thread_t * opj_thread_create | ( | opj_thread_fn | thread_fn,
|  | void * | user_data
| ) |  |

Creates a new thread.

Parameters

  thread_fn | Function to run in the new thread.
  user_data | user data provided to the thread function. Might be NULL.

Returns
  a thread handle or NULL in case of failure (can for example happen if the library is built without thread support)

Referenced by opj_thread_pool_setup().

## opj_thread_join()

void opj_thread_join | ( | opj_thread_t * | thread | ) |

Wait for a thread to be finished and release associated resources to the thread handle.

Parameters

  thread | the thread to wait for being finished.

Referenced by opj_thread_pool_destroy().

## opj_thread_pool_create()

opj_thread_pool_t * opj_thread_pool_create | ( | int | num_threads | ) |

Create a new thread pool.

num_thread must nominally be >= 1 to create a real thread pool. If num_threads is negative or null, then a dummy thread pool will be created. All functions operating on the thread pool will work, but job submission will be run synchronously in the calling thread.

Parameters

  num_threads | the number of threads to allocate for this thread pool.

Returns
  a thread pool handle, or NULL in case of failure (can for example happen if the library is built without thread support)

References opj_thread_pool_t::mutex, opj_calloc(), opj_free(), opj_mutex_create(), opj_thread_pool_destroy(), opj_thread_pool_setup(), opj_tls_new(), OPJWTS_OK, opj_thread_pool_t::state, and opj_thread_pool_t::tls.

Referenced by main(), opj_j2k_create_compress(), opj_j2k_create_decompress(), and opj_j2k_set_threads().

## opj_thread_pool_destroy()

void opj_thread_pool_destroy | ( | opj_thread_pool_t * | tp | ) |

Destroy a thread pool.

Parameters

  tp | the thread pool handle.

References opj_worker_thread_t::cond, opj_thread_pool_t::cond, opj_worker_thread_t::mutex, opj_thread_pool_t::mutex, opj_worker_thread_list_t::next, opj_cond_destroy(), opj_cond_signal(), opj_free(), opj_mutex_destroy(), opj_mutex_lock(), opj_mutex_unlock(), opj_thread_join(), opj_thread_pool_wait_completion(), opj_tls_destroy(), OPJWTS_STOP, opj_thread_pool_t::state, opj_worker_thread_t::thread, opj_thread_pool_t::tls, opj_thread_pool_t::waiting_worker_thread_list, opj_thread_pool_t::worker_threads, and opj_thread_pool_t::worker_threads_count.

Referenced by main(), opj_j2k_destroy(), opj_j2k_set_threads(), and opj_thread_pool_create().

## opj_thread_pool_get_next_job()

static opj_worker_thread_job_t * opj_thread_pool_get_next_job | ( | opj_thread_pool_t * | tp,
|  | opj_worker_thread_t * | worker_thread,
|  | OPJ_BOOL | signal_job_finished
| ) |  |

static

References opj_worker_thread_t::cond, opj_thread_pool_t::cond, opj_job_list_t::job, opj_thread_pool_t::job_queue, opj_worker_thread_t::marked_as_waiting, opj_worker_thread_t::mutex, opj_thread_pool_t::mutex, opj_job_list_t::next, opj_worker_thread_list_t::next, opj_cond_signal(), opj_cond_wait(), OPJ_FALSE, opj_free(), opj_malloc(), opj_mutex_lock(), opj_mutex_unlock(), OPJ_TRUE, OPJWTS_ERROR, OPJWTS_STOP, opj_thread_pool_t::pending_jobs_count, opj_thread_pool_t::signaling_threshold, opj_thread_pool_t::state, opj_thread_pool_t::waiting_worker_thread_count, opj_thread_pool_t::waiting_worker_thread_list, opj_worker_thread_list_t::worker_thread, and opj_thread_pool_t::worker_threads_count.

Referenced by opj_worker_thread_function().

## opj_thread_pool_get_thread_count()

int opj_thread_pool_get_thread_count | ( | opj_thread_pool_t * | tp | ) |

Return the number of threads associated with the thread pool.

Parameters

  tp | the thread pool handle.

Returns
  number of threads associated with the thread pool.

References opj_thread_pool_t::worker_threads_count.

Referenced by opj_dwt_decode_tile(), opj_dwt_decode_tile_97(), opj_dwt_encode_procedure(), and opj_t1_decode_cblks().

## opj_thread_pool_setup()

static OPJ_BOOL opj_thread_pool_setup | ( | opj_thread_pool_t * | tp,
|  | int | num_threads
| ) |  |

static

References opj_worker_thread_t::cond, opj_thread_pool_t::cond, opj_worker_thread_t::marked_as_waiting, opj_worker_thread_t::mutex, opj_thread_pool_t::mutex, opj_calloc(), opj_cond_create(), opj_cond_destroy(), opj_cond_wait(), OPJ_FALSE, opj_mutex_create(), opj_mutex_destroy(), opj_mutex_lock(), opj_mutex_unlock(), opj_thread_create(), OPJ_TRUE, opj_worker_thread_function(), OPJWTS_ERROR, opj_thread_pool_t::state, opj_worker_thread_t::thread, opj_worker_thread_t::tp, opj_thread_pool_t::waiting_worker_thread_count, opj_thread_pool_t::worker_threads, and opj_thread_pool_t::worker_threads_count.

Referenced by opj_thread_pool_create().

## opj_thread_pool_submit_job()

OPJ_BOOL opj_thread_pool_submit_job | ( | opj_thread_pool_t * | tp,
|  | opj_job_fn | job_fn,
|  | void * | user_data
| ) |  |

Submit a new job to be run by one of the thread in the thread pool.

The job ( thread_fn, user_data ) will be added in the queue of jobs managed by the thread pool, and run by the first thread that is no longer busy.

Parameters

  tp | the thread pool handle.
  job_fn | Function to run. Must not be NULL.
  user_data | User data provided to thread_fn.

Returns
  OPJ_TRUE if the job was successfully submitted.

References opj_worker_thread_t::cond, opj_thread_pool_t::cond, opj_job_list_t::job, opj_worker_thread_job_t::job_fn, opj_thread_pool_t::job_queue, opj_worker_thread_t::marked_as_waiting, opj_worker_thread_t::mutex, opj_thread_pool_t::mutex, opj_job_list_t::next, opj_worker_thread_list_t::next, opj_cond_signal(), opj_cond_wait(), OPJ_FALSE, opj_free(), opj_malloc(), opj_mutex_lock(), opj_mutex_unlock(), OPJ_TRUE, opj_thread_pool_t::pending_jobs_count, opj_thread_pool_t::signaling_threshold, opj_thread_pool_t::tls, opj_worker_thread_job_t::user_data, opj_thread_pool_t::waiting_worker_thread_count, opj_thread_pool_t::waiting_worker_thread_list, opj_worker_thread_list_t::worker_thread, and opj_thread_pool_t::worker_threads_count.

Referenced by opj_dwt_decode_tile(), opj_dwt_decode_tile_97(), opj_dwt_encode_procedure(), opj_t1_decode_cblks(), and opj_t1_encode_cblks().

## opj_thread_pool_wait_completion()

void opj_thread_pool_wait_completion | ( | opj_thread_pool_t * | tp,
|  | int | max_remaining_jobs
| ) |  |

Wait that no more than max_remaining_jobs jobs are remaining in the queue of the thread pool.

The aim of this function is to avoid submitting too many jobs while the thread pool cannot cope fast enough with them, which would result potentially in out-of-memory situations with too many job descriptions being queued.

Parameters

  tp | the thread pool handle
  max_remaining_jobs | maximum number of jobs allowed to be queued without waiting.

References opj_thread_pool_t::cond, opj_thread_pool_t::mutex, opj_cond_wait(), opj_mutex_lock(), opj_mutex_unlock(), opj_thread_pool_t::pending_jobs_count, and opj_thread_pool_t::signaling_threshold.

Referenced by opj_dwt_decode_tile(), opj_dwt_decode_tile_97(), opj_dwt_encode_procedure(), opj_t1_encode_cblks(), opj_tcd_t1_decode(), and opj_thread_pool_destroy().

## opj_tls_destroy()

static void opj_tls_destroy | ( | opj_tls_t * | tls | ) |

static

References opj_tls_t::key_val, opj_tls_t::key_val_count, opj_free(), opj_tls_key_val_t::opj_free_func, and opj_tls_key_val_t::value.

Referenced by opj_thread_pool_destroy(), and opj_worker_thread_function().

## opj_tls_get()

void * opj_tls_get | ( | opj_tls_t * | tls,
|  | int | key
| ) |  |

Get a thread local value corresponding to the provided key.

Parameters

  tls | thread local storage handle
  key | key whose value to retrieve.

Returns
  value associated with the key, or NULL is missing.

References opj_tls_key_val_t::key, opj_tls_t::key_val, opj_tls_t::key_val_count, and opj_tls_key_val_t::value.

Referenced by opj_t1_cblk_encode_processor(), and opj_t1_clbl_decode_processor().

## opj_tls_new()

static opj_tls_t * opj_tls_new | ( | void |  | ) |

static

References opj_calloc().

Referenced by opj_thread_pool_create(), and opj_worker_thread_function().

## opj_tls_set()

OPJ_BOOL opj_tls_set | ( | opj_tls_t * | tls,
|  | int | key,
|  | void * | value,
|  | opj_tls_free_func | free_func
| ) |  |

Set a thread local value corresponding to the provided key.

Parameters

  tls | thread local storage handle
  key | key whose value to set.
  value | value to set (may be NULL).
  free_func | function to call currently installed value.

Returns
  OPJ_TRUE if successful.

References opj_tls_key_val_t::key, opj_tls_t::key_val, opj_tls_t::key_val_count, OPJ_FALSE, opj_tls_key_val_t::opj_free_func, opj_realloc(), OPJ_TRUE, and opj_tls_key_val_t::value.

Referenced by opj_t1_cblk_encode_processor(), and opj_t1_clbl_decode_processor().

## opj_worker_thread_function()

static void opj_worker_thread_function | ( | void * | user_data | ) |

static

References opj_worker_thread_job_t::job_fn, OPJ_FALSE, opj_free(), opj_thread_pool_get_next_job(), opj_tls_destroy(), opj_tls_new(), OPJ_TRUE, opj_worker_thread_t::tp, and opj_worker_thread_job_t::user_data.

Referenced by opj_thread_pool_setup().