1 /* Copyright (C) 2010-2020 The RetroArch team
3 * ---------------------------------------------------------------------------------------
4 * The following license statement only applies to this file (rthreads.h).
5 * ---------------------------------------------------------------------------------------
7 * Permission is hereby granted, free of charge,
8 * to any person obtaining a copy of this software and associated documentation files (the "Software"),
9 * to deal in the Software without restriction, including without limitation the rights to
10 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
11 * and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
13 * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
16 * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
18 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
19 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
23 #ifndef __LIBRETRO_SDK_RTHREADS_H__
24 #define __LIBRETRO_SDK_RTHREADS_H__
26 #include <retro_common_api.h>
30 #include <retro_inline.h>
31 #include <retro_miscellaneous.h>
35 typedef struct sthread sthread_t;
36 typedef struct slock slock_t;
37 typedef struct scond scond_t;
39 #ifdef HAVE_THREAD_STORAGE
40 typedef unsigned sthread_tls_t;
45 * @start_routine : thread entry callback function
46 * @userdata : pointer to userdata that will be made
47 * available in thread entry callback function
49 * Create a new thread.
51 * Returns: pointer to new thread if successful, otherwise NULL.
53 sthread_t *sthread_create(void (*thread_func)(void*), void *userdata);
56 * sthread_create_with_priority:
57 * @start_routine : thread entry callback function
58 * @userdata : pointer to userdata that will be made
59 * available in thread entry callback function
60 * @thread_priority : thread priority hint value from [1-100]
62 * Create a new thread. It is possible for the caller to give a hint
63 * for the thread's priority from [1-100]. Any passed in @thread_priority
64 * values that are outside of this range will cause sthread_create() to
65 * create a new thread using the operating system's default thread
68 * Returns: pointer to new thread if successful, otherwise NULL.
70 sthread_t *sthread_create_with_priority(void (*thread_func)(void*), void *userdata, int thread_priority);
74 * @thread : pointer to thread object
76 * Detach a thread. When a detached thread terminates, its
77 * resource sare automatically released back to the system
78 * without the need for another thread to join with the
81 * Returns: 0 on success, otherwise it returns a non-zero error number.
83 int sthread_detach(sthread_t *thread);
87 * @thread : pointer to thread object
89 * Join with a terminated thread. Waits for the thread specified by
90 * @thread to terminate. If that thread has already terminated, then
91 * it will return immediately. The thread specified by @thread must
94 * Returns: 0 on success, otherwise it returns a non-zero error number.
96 void sthread_join(sthread_t *thread);
100 * @thread : pointer to thread object
102 * Returns: true (1) if calling thread is the specified thread
104 bool sthread_isself(sthread_t *thread);
109 * Create and initialize a new mutex. Must be manually
112 * Returns: pointer to a new mutex if successful, otherwise NULL.
114 slock_t *slock_new(void);
118 * @lock : pointer to mutex object
122 void slock_free(slock_t *lock);
126 * @lock : pointer to mutex object
128 * Locks a mutex. If a mutex is already locked by
129 * another thread, the calling thread shall block until
130 * the mutex becomes available.
132 void slock_lock(slock_t *lock);
136 * @lock : pointer to mutex object
138 * Attempts to lock a mutex. If a mutex is already locked by
139 * another thread, return false. If the lock is acquired, return true.
141 bool slock_try_lock(slock_t *lock);
145 * @lock : pointer to mutex object
149 void slock_unlock(slock_t *lock);
154 * Creates and initializes a condition variable. Must
157 * Returns: pointer to new condition variable on success,
160 scond_t *scond_new(void);
164 * @cond : pointer to condition variable object
166 * Frees a condition variable.
168 void scond_free(scond_t *cond);
172 * @cond : pointer to condition variable object
173 * @lock : pointer to mutex object
175 * Block on a condition variable (i.e. wait on a condition).
177 void scond_wait(scond_t *cond, slock_t *lock);
180 * scond_wait_timeout:
181 * @cond : pointer to condition variable object
182 * @lock : pointer to mutex object
183 * @timeout_us : timeout (in microseconds)
185 * Try to block on a condition variable (i.e. wait on a condition) until
186 * @timeout_us elapses.
188 * Returns: false (0) if timeout elapses before condition variable is
189 * signaled or broadcast, otherwise true (1).
191 bool scond_wait_timeout(scond_t *cond, slock_t *lock, int64_t timeout_us);
195 * @cond : pointer to condition variable object
197 * Broadcast a condition. Unblocks all threads currently blocked
198 * on the specified condition variable @cond.
200 int scond_broadcast(scond_t *cond);
204 * @cond : pointer to condition variable object
206 * Signal a condition. Unblocks at least one of the threads currently blocked
207 * on the specified condition variable @cond.
209 void scond_signal(scond_t *cond);
211 #ifdef HAVE_THREAD_STORAGE
213 * @brief Creates a thread local storage key
215 * This function shall create thread-specific data key visible to all threads in
216 * the process. The same key can be used by multiple threads to store
219 * When the key is created NULL shall be associated with it in all active
220 * threads. Whenever a new thread is spawned the all defined keys will be
221 * associated with NULL on that thread.
224 * @return whether the operation suceeded or not
226 bool sthread_tls_create(sthread_tls_t *tls);
229 * @brief Deletes a thread local storage
231 * @return whether the operation suceeded or not
233 bool sthread_tls_delete(sthread_tls_t *tls);
236 * @brief Retrieves thread specific data associated with a key
238 * There is no way to tell whether this function failed.
243 void *sthread_tls_get(sthread_tls_t *tls);
246 * @brief Binds thread specific data to a key
248 * @return Whether the operation suceeded or not
250 bool sthread_tls_set(sthread_tls_t *tls, const void *data);
254 * @brief Get thread ID of specified thread
256 * @return The ID of the specified thread
258 uintptr_t sthread_get_thread_id(sthread_t *thread);
261 * @brief Get thread ID of the current thread
263 * @return The ID of the current thread
265 uintptr_t sthread_get_current_thread_id(void);