thread.h File Reference

Thread API. More...

#include "openjpeg.h"

Go to the source code of this file.

Mutex
typedef struct opj_mutex_t	opj_mutex_t
	Opaque type for a mutex. More...
opj_mutex_t *	opj_mutex_create (void)
	Creates a mutex. More...
void	opj_mutex_lock (opj_mutex_t *mutex)
	Lock/acquire the mutex. More...
void	opj_mutex_unlock (opj_mutex_t *mutex)
	Unlock/release the mutex. More...
void	opj_mutex_destroy (opj_mutex_t *mutex)
	Destroy a mutex. More...

Condition
typedef struct opj_cond_t	opj_cond_t
	Opaque type for a condition. More...
opj_cond_t *	opj_cond_create (void)
	Creates a condition. More...
void	opj_cond_wait (opj_cond_t *cond, opj_mutex_t *mutex)
	Wait for the condition to be signaled. More...
void	opj_cond_signal (opj_cond_t *cond)
	Signal waiting threads on a condition. More...
void	opj_cond_destroy (opj_cond_t *cond)
	Destroy a condition. More...

Thread
typedef struct opj_thread_t	opj_thread_t
	Opaque type for a thread handle. More...
typedef void(*	opj_thread_fn) (void *user_data)
	User function to execute in a thread. More...
opj_thread_t *	opj_thread_create (opj_thread_fn thread_fn, void *user_data)
	Creates a new thread. More...
void	opj_thread_join (opj_thread_t *thread)
	Wait for a thread to be finished and release associated resources to the thread handle. More...

Thread local storage
typedef struct opj_tls_t	opj_tls_t
	Opaque type for a thread local storage. More...
typedef void(*	opj_tls_free_func) (void *value)
	Type of the function used to free a TLS value. More...
void *	opj_tls_get (opj_tls_t *tls, int key)
	Get a thread local value corresponding to the provided key. More...
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. More...

Thread pool
typedef struct opj_thread_pool_t	opj_thread_pool_t
	Opaque type for a thread pool. More...
typedef void(*	opj_job_fn) (void *user_data, opj_tls_t *tls)
	User function to execute in a thread. More...
opj_thread_pool_t *	opj_thread_pool_create (int num_threads)
	Create a new thread pool. More...
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. More...
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. More...
int	opj_thread_pool_get_thread_count (opj_thread_pool_t *tp)
	Return the number of threads associated with the thread pool. More...
void	opj_thread_pool_destroy (opj_thread_pool_t *tp)
	Destroy a thread pool. More...

Detailed Description

Thread API.

The functions in thread.c have for goal to manage mutex, conditions, thread creation and thread pools that accept jobs.

Typedef Documentation

opj_cond_t

typedef struct opj_cond_t opj_cond_t

Opaque type for a condition.

opj_job_fn

typedef void(* opj_job_fn) (void *user_data, opj_tls_t *tls)

User function to execute in a thread.

Parameters

user_data	user data provided with opj_thread_create()
tls	handle to thread local storage

opj_mutex_t

typedef struct opj_mutex_t opj_mutex_t

Opaque type for a mutex.

opj_thread_fn

typedef void(* opj_thread_fn) (void *user_data)

User function to execute in a thread.

Parameters

user_data

user data provided with opj_thread_create()

opj_thread_pool_t

typedef struct opj_thread_pool_t opj_thread_pool_t

Opaque type for a thread pool.

opj_thread_t

typedef struct opj_thread_t opj_thread_t

Opaque type for a thread handle.

opj_tls_free_func

typedef void(* opj_tls_free_func) (void *value)

Type of the function used to free a TLS value.

opj_tls_t

typedef struct opj_tls_t opj_tls_t

Opaque type for a thread local storage.

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

Signaling thread :

opj_mutex_lock(mutex);
some_application_level_condition = TRUE;
opj_cond_signal(cond);
opj_mutex_unlock(mutex);

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