Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/thirdparty/openjpeg/src/lib/openjp2/thread.h @ 2:b50eed0cc0ef upstream

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. The directory name has changed: no version number in the expanded directory now.
author Franz Glasner <fzglas.hg@dom66.de>
date Mon, 15 Sep 2025 11:43:07 +0200
parents
children
comparison
equal deleted inserted replaced
1:1d09e1dec1d9 2:b50eed0cc0ef
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 */