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 */ 257