src/lib/openjp2/thread.h

   1 /*
   2  * The copyright in this software is being made available under the 2-clauses
   3  * BSD License, included below. This software may be subject to other third
   4  * party and contributor rights, including patent rights, and no such rights
   5  * are granted under this license.
   6  *
   7  * Copyright (c) 2016, Even Rouault
   8  * All rights reserved.
   9  *
  10  * Redistribution and use in source and binary forms, with or without
  11  * modification, are permitted provided that the following conditions
  12  * are met:
  13  * 1. Redistributions of source code must retain the above copyright
  14  *    notice, this list of conditions and the following disclaimer.
  15  * 2. Redistributions in binary form must reproduce the above copyright
  16  *    notice, this list of conditions and the following disclaimer in the
  17  *    documentation and/or other materials provided with the distribution.
  18  *
  19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS `AS IS'
  20  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22  * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  23  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  24  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  25  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  26  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  27  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  28  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  29  * POSSIBILITY OF SUCH DAMAGE.
  30  */
  31
  32 #ifndef THREAD_H
  33 #define THREAD_H
  34
  35 #include "openjpeg.h"
  36
  37 /**
  38 @file thread.h
  39 @brief Thread API
  40
  41 The functions in thread.c have for goal to manage mutex, conditions, thread
  42 creation and thread pools that accept jobs.
  43 */
  44
  45 /** @defgroup THREAD THREAD - Mutex, conditions, threads and thread pools */
  46 /*@{*/
  47
  48 /** @name Mutex */
  49 /*@{*/
  50
  51 /** Opaque type for a mutex */
  52 typedef struct opj_mutex_t opj_mutex_t;
  53
  54 /** Creates a mutex.
  55  * @return the mutex or NULL in case of error (can for example happen if the library
  56  * is built without thread support)
  57  */
  58 opj_mutex_t* opj_mutex_create(void);
  59
  60 /** Lock/acquire the mutex.
  61  * @param mutex the mutex to acquire.
  62  */
  63 void opj_mutex_lock(opj_mutex_t* mutex);
  64
  65 /** Unlock/release the mutex.
  66  * @param mutex the mutex to release.
  67  */
  68 void opj_mutex_unlock(opj_mutex_t* mutex);
  69
  70 /** Destroy a mutex
  71  * @param mutex the mutex to destroy.
  72  */
  73 void opj_mutex_destroy(opj_mutex_t* mutex);
  74
  75 /*@}*/
  76
  77 /** @name Condition */
  78 /*@{*/
  79
  80 /** Opaque type for a condition */
  81 typedef struct opj_cond_t opj_cond_t;
  82
  83 /** Creates a condition.
  84  * @return the condition or NULL in case of error (can for example happen if the library
  85  * is built without thread support)
  86  */
  87 opj_cond_t* opj_cond_create(void);
  88
  89 /** Wait for the condition to be signaled.
  90  * The semantics is the same as the POSIX pthread_cond_wait.
  91  * The provided mutex *must* be acquired before calling this function, and
  92  * released afterwards.
  93  * The mutex will be released by this function while it must wait for the condition
  94  * and reacquired afterwards.
  95  * In some particular situations, the function might return even if the condition is not signaled
  96  * with opj_cond_signal(), hence the need to check with an application level
  97  * mechanism.
  98  *
  99  * Waiting thread :
 100  * \code
 101  *    opj_mutex_lock(mutex);
 102  *    while( !some_application_level_condition )
 103  *    {
 104  *        opj_cond_wait(cond, mutex);
 105  *    }
 106  *    opj_mutex_unlock(mutex);
 107  * \endcode
 108  *
 109  * Signaling thread :
 110  * \code
 111  *    opj_mutex_lock(mutex);
 112  *    some_application_level_condition = TRUE;
 113  *    opj_cond_signal(cond);
 114  *    opj_mutex_unlock(mutex);
 115  * \endcode
 116  *
 117  * @param cond the condition to wait.
 118  * @param mutex the mutex (in acquired state before calling this function)
 119  */
 120 void opj_cond_wait(opj_cond_t* cond, opj_mutex_t* mutex);
 121
 122 /** Signal waiting threads on a condition.
 123  * One of the thread waiting with opj_cond_wait() will be waken up.
 124  * It is strongly advised that this call is done with the mutex that is used
 125  * by opj_cond_wait(), in a acquired state.
 126  * @param cond the condition to signal.
 127  */
 128 void opj_cond_signal(opj_cond_t* cond);
 129
 130 /** Destroy a condition
 131  * @param cond the condition to destroy.
 132  */
 133 void opj_cond_destroy(opj_cond_t* cond);
 134
 135 /*@}*/
 136
 137 /** @name Thread */
 138 /*@{*/
 139
 140 /** Opaque type for a thread handle */
 141 typedef struct opj_thread_t opj_thread_t;
 142
 143 /** User function to execute in a thread
 144  * @param user_data user data provided with opj_thread_create()
 145  */
 146 typedef void (*opj_thread_fn)(void* user_data);
 147
 148 /** Creates a new thread.
 149  * @param thread_fn Function to run in the new thread.
 150  * @param user_data user data provided to the thread function. Might be NULL.
 151  * @return a thread handle or NULL in case of failure (can for example happen if the library
 152  * is built without thread support)
 153  */
 154 opj_thread_t* opj_thread_create(opj_thread_fn thread_fn, void* user_data);
 155
 156 /** Wait for a thread to be finished and release associated resources to the
 157  * thread handle.
 158  * @param thread the thread to wait for being finished.
 159  */
 160 void opj_thread_join(opj_thread_t* thread);
 161
 162 /*@}*/
 163
 164 /** @name Thread local storage */
 165 /*@{*/
 166 /** Opaque type for a thread local storage */
 167 typedef struct opj_tls_t opj_tls_t;
 168
 169 /** Get a thread local value corresponding to the provided key.
 170  * @param tls thread local storage handle
 171  * @param key key whose value to retrieve.
 172  * @return value associated with the key, or NULL is missing.
 173  */
 174 void* opj_tls_get(opj_tls_t* tls, int key);
 175
 176 /** Type of the function used to free a TLS value */
 177 typedef void (*opj_tls_free_func)(void* value);
 178
 179 /** Set a thread local value corresponding to the provided key.
 180  * @param tls thread local storage handle
 181  * @param key key whose value to set.
 182  * @param value value to set (may be NULL).
 183  * @param free_func function to call currently installed value.
 184  * @return OPJ_TRUE if successful.
 185  */
 186 OPJ_BOOL opj_tls_set(opj_tls_t* tls, int key, void* value,
 187                      opj_tls_free_func free_func);
 188
 189 /*@}*/
 190
 191 /** @name Thread pool */
 192 /*@{*/
 193
 194 /** Opaque type for a thread pool */
 195 typedef struct opj_thread_pool_t opj_thread_pool_t;
 196
 197 /** Create a new thread pool.
 198  * num_thread must nominally be >= 1 to create a real thread pool. If num_threads
 199  * is negative or null, then a dummy thread pool will be created. All functions
 200  * operating on the thread pool will work, but job submission will be run
 201  * synchronously in the calling thread.
 202  *
 203  * @param num_threads the number of threads to allocate for this thread pool.
 204  * @return a thread pool handle, or NULL in case of failure (can for example happen if the library
 205  * is built without thread support)
 206  */
 207 opj_thread_pool_t* opj_thread_pool_create(int num_threads);
 208
 209 /** User function to execute in a thread
 210  * @param user_data user data provided with opj_thread_create()
 211  * @param tls handle to thread local storage
 212  */
 213 typedef void (*opj_job_fn)(void* user_data, opj_tls_t* tls);
 214
 215
 216 /** Submit a new job to be run by one of the thread in the thread pool.
 217  * The job ( thread_fn, user_data ) will be added in the queue of jobs managed
 218  * by the thread pool, and run by the first thread that is no longer busy.
 219  *
 220  * @param tp the thread pool handle.
 221  * @param job_fn Function to run. Must not be NULL.
 222  * @param user_data User data provided to thread_fn.
 223  * @return OPJ_TRUE if the job was successfully submitted.
 224  */
 225 OPJ_BOOL opj_thread_pool_submit_job(opj_thread_pool_t* tp, opj_job_fn job_fn,
 226                                     void* user_data);
 227
 228 /** Wait that no more than max_remaining_jobs jobs are remaining in the queue of
 229  * the thread pool. The aim of this function is to avoid submitting too many
 230  * jobs while the thread pool cannot cope fast enough with them, which would
 231  * result potentially in out-of-memory situations with too many job descriptions
 232  * being queued.
 233  *
 234  * @param tp the thread pool handle
 235  * @param max_remaining_jobs maximum number of jobs allowed to be queued without waiting.
 236  */
 237 void opj_thread_pool_wait_completion(opj_thread_pool_t* tp,
 238                                      int max_remaining_jobs);
 239
 240 /** Return the number of threads associated with the thread pool.
 241  *
 242  * @param tp the thread pool handle.
 243  * @return number of threads associated with the thread pool.
 244  */
 245 int opj_thread_pool_get_thread_count(opj_thread_pool_t* tp);
 246
 247 /** Destroy a thread pool.
 248  * @param tp the thread pool handle.
 249  */
 250 void opj_thread_pool_destroy(opj_thread_pool_t* tp);
 251
 252 /*@}*/
 253
 254 /*@}*/
 255
 256 #endif /* THREAD_H */