1 /* Copyright (C) 2010-2015 The RetroArch team 2 * 3 * --------------------------------------------------------------------------------------- 4 * The following license statement only applies to this file (rthreads.h). 5 * --------------------------------------------------------------------------------------- 6 * 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: 12 * 13 * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 14 * 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. 21 */ 22 23 #ifndef __LIBRETRO_SDK_RTHREADS_H__ 24 #define __LIBRETRO_SDK_RTHREADS_H__ 25 26 #include <retro_common_api.h> 27 28 #include <boolean.h> 29 #include <stdint.h> 30 #include <retro_inline.h> 31 #include <retro_miscellaneous.h> 32 33 RETRO_BEGIN_DECLS 34 35 typedef struct sthread sthread_t; 36 typedef struct slock slock_t; 37 typedef struct scond scond_t; 38 39 /** 40 * sthread_create: 41 * @start_routine : thread entry callback function 42 * @userdata : pointer to userdata that will be made 43 * available in thread entry callback function 44 * 45 * Create a new thread. 46 * 47 * Returns: pointer to new thread if successful, otherwise NULL. 48 */ 49 sthread_t *sthread_create(void (*thread_func)(void*), void *userdata); 50 51 /** 52 * sthread_detach: 53 * @thread : pointer to thread object 54 * 55 * Detach a thread. When a detached thread terminates, its 56 * resource sare automatically released back to the system 57 * without the need for another thread to join with the 58 * terminated thread. 59 * 60 * Returns: 0 on success, otherwise it returns a non-zero error number. 61 */ 62 int sthread_detach(sthread_t *thread); 63 64 /** 65 * sthread_join: 66 * @thread : pointer to thread object 67 * 68 * Join with a terminated thread. Waits for the thread specified by 69 * @thread to terminate. If that thread has already terminated, then 70 * it will return immediately. The thread specified by @thread must 71 * be joinable. 72 * 73 * Returns: 0 on success, otherwise it returns a non-zero error number. 74 */ 75 void sthread_join(sthread_t *thread); 76 77 /** 78 * sthread_isself: 79 * @thread : pointer to thread object 80 * 81 * Join with a terminated thread. Waits for the thread specified by 82 * @thread to terminate. If that thread has already terminated, then 83 * it will return immediately. The thread specified by @thread must 84 * be joinable. 85 * 86 * Returns: true (1) if calling thread is the specified thread 87 */ 88 bool sthread_isself(sthread_t *thread); 89 90 /** 91 * slock_new: 92 * 93 * Create and initialize a new mutex. Must be manually 94 * freed. 95 * 96 * Returns: pointer to a new mutex if successful, otherwise NULL. 97 **/ 98 slock_t *slock_new(void); 99 100 /** 101 * slock_free: 102 * @lock : pointer to mutex object 103 * 104 * Frees a mutex. 105 **/ 106 void slock_free(slock_t *lock); 107 108 /** 109 * slock_lock: 110 * @lock : pointer to mutex object 111 * 112 * Locks a mutex. If a mutex is already locked by 113 * another thread, the calling thread shall block until 114 * the mutex becomes available. 115 **/ 116 void slock_lock(slock_t *lock); 117 118 /** 119 * slock_unlock: 120 * @lock : pointer to mutex object 121 * 122 * Unlocks a mutex. 123 **/ 124 void slock_unlock(slock_t *lock); 125 126 /** 127 * scond_new: 128 * 129 * Creates and initializes a condition variable. Must 130 * be manually freed. 131 * 132 * Returns: pointer to new condition variable on success, 133 * otherwise NULL. 134 **/ 135 scond_t *scond_new(void); 136 137 /** 138 * scond_free: 139 * @cond : pointer to condition variable object 140 * 141 * Frees a condition variable. 142 **/ 143 void scond_free(scond_t *cond); 144 145 /** 146 * scond_wait: 147 * @cond : pointer to condition variable object 148 * @lock : pointer to mutex object 149 * 150 * Block on a condition variable (i.e. wait on a condition). 151 **/ 152 void scond_wait(scond_t *cond, slock_t *lock); 153 154 /** 155 * scond_wait_timeout: 156 * @cond : pointer to condition variable object 157 * @lock : pointer to mutex object 158 * @timeout_us : timeout (in microseconds) 159 * 160 * Try to block on a condition variable (i.e. wait on a condition) until 161 * @timeout_us elapses. 162 * 163 * Returns: false (0) if timeout elapses before condition variable is 164 * signaled or broadcast, otherwise true (1). 165 **/ 166 bool scond_wait_timeout(scond_t *cond, slock_t *lock, int64_t timeout_us); 167 168 /** 169 * scond_broadcast: 170 * @cond : pointer to condition variable object 171 * 172 * Broadcast a condition. Unblocks all threads currently blocked 173 * on the specified condition variable @cond. 174 **/ 175 int scond_broadcast(scond_t *cond); 176 177 /** 178 * scond_signal: 179 * @cond : pointer to condition variable object 180 * 181 * Signal a condition. Unblocks at least one of the threads currently blocked 182 * on the specified condition variable @cond. 183 **/ 184 void scond_signal(scond_t *cond); 185 186 RETRO_END_DECLS 187 188 #endif 189