| 1 | /* -*- mode: c; tab-width: 2; indent-tabs-mode: nil; -*- |
| 2 | Copyright (c) 2012 Marcus Geelnard |
| 3 | |
| 4 | This software is provided 'as-is', without any express or implied |
| 5 | warranty. In no event will the authors be held liable for any damages |
| 6 | arising from the use of this software. |
| 7 | |
| 8 | Permission is granted to anyone to use this software for any purpose, |
| 9 | including commercial applications, and to alter it and redistribute it |
| 10 | freely, subject to the following restrictions: |
| 11 | |
| 12 | 1. The origin of this software must not be misrepresented; you must not |
| 13 | claim that you wrote the original software. If you use this software |
| 14 | in a product, an acknowledgment in the product documentation would be |
| 15 | appreciated but is not required. |
| 16 | |
| 17 | 2. Altered source versions must be plainly marked as such, and must not be |
| 18 | misrepresented as being the original software. |
| 19 | |
| 20 | 3. This notice may not be removed or altered from any source |
| 21 | distribution. |
| 22 | */ |
| 23 | |
| 24 | #ifndef _TINYCTHREAD_H_ |
| 25 | #define _TINYCTHREAD_H_ |
| 26 | |
| 27 | /** |
| 28 | * @file |
| 29 | * @mainpage TinyCThread API Reference |
| 30 | * |
| 31 | * @section intro_sec Introduction |
| 32 | * TinyCThread is a minimal, portable implementation of basic threading |
| 33 | * classes for C. |
| 34 | * |
| 35 | * They closely mimic the functionality and naming of the C11 standard, and |
| 36 | * should be easily replaceable with the corresponding standard variants. |
| 37 | * |
| 38 | * @section port_sec Portability |
| 39 | * The Win32 variant uses the native Win32 API for implementing the thread |
| 40 | * classes, while for other systems, the POSIX threads API (pthread) is used. |
| 41 | * |
| 42 | * @section misc_sec Miscellaneous |
| 43 | * The following special keywords are available: #_Thread_local. |
| 44 | * |
| 45 | * For more detailed information, browse the different sections of this |
| 46 | * documentation. A good place to start is: |
| 47 | * tinycthread.h. |
| 48 | */ |
| 49 | |
| 50 | /* Which platform are we on? */ |
| 51 | #if !defined(_TTHREAD_PLATFORM_DEFINED_) |
| 52 | #if defined(_WIN32) || defined(__WIN32__) || defined(__WINDOWS__) |
| 53 | #define _TTHREAD_WIN32_ |
| 54 | #else |
| 55 | #define _TTHREAD_POSIX_ |
| 56 | #endif |
| 57 | #define _TTHREAD_PLATFORM_DEFINED_ |
| 58 | #endif |
| 59 | |
| 60 | /* Activate some POSIX functionality (e.g. clock_gettime and recursive mutexes) */ |
| 61 | #if defined(_TTHREAD_POSIX_) |
| 62 | #undef _FEATURES_H |
| 63 | #if !defined(_GNU_SOURCE) |
| 64 | #define _GNU_SOURCE |
| 65 | #endif |
| 66 | #if !defined(_POSIX_C_SOURCE) || ((_POSIX_C_SOURCE - 0) < 199309L) |
| 67 | #undef _POSIX_C_SOURCE |
| 68 | #define _POSIX_C_SOURCE 199309L |
| 69 | #endif |
| 70 | #if !defined(_XOPEN_SOURCE) || ((_XOPEN_SOURCE - 0) < 500) |
| 71 | #undef _XOPEN_SOURCE |
| 72 | #define _XOPEN_SOURCE 500 |
| 73 | #endif |
| 74 | #endif |
| 75 | |
| 76 | /* Generic includes */ |
| 77 | #include <time.h> |
| 78 | |
| 79 | /* Platform specific includes */ |
| 80 | #if defined(_TTHREAD_POSIX_) |
| 81 | #include <sys/time.h> |
| 82 | #include <pthread.h> |
| 83 | #elif defined(_TTHREAD_WIN32_) |
| 84 | #ifndef WIN32_LEAN_AND_MEAN |
| 85 | #define WIN32_LEAN_AND_MEAN |
| 86 | #define __UNDEF_LEAN_AND_MEAN |
| 87 | #endif |
| 88 | #include <windows.h> |
| 89 | #ifdef __UNDEF_LEAN_AND_MEAN |
| 90 | #undef WIN32_LEAN_AND_MEAN |
| 91 | #undef __UNDEF_LEAN_AND_MEAN |
| 92 | #endif |
| 93 | #endif |
| 94 | |
| 95 | /* Workaround for missing TIME_UTC: If time.h doesn't provide TIME_UTC, |
| 96 | it's quite likely that libc does not support it either. Hence, fall back to |
| 97 | the only other supported time specifier: CLOCK_REALTIME (and if that fails, |
| 98 | we're probably emulating clock_gettime anyway, so anything goes). */ |
| 99 | #ifndef TIME_UTC |
| 100 | #ifdef CLOCK_REALTIME |
| 101 | #define TIME_UTC CLOCK_REALTIME |
| 102 | #else |
| 103 | #define TIME_UTC 0 |
| 104 | #endif |
| 105 | #endif |
| 106 | |
| 107 | /* Workaround for missing clock_gettime (most Windows compilers, afaik) */ |
| 108 | #if defined(_TTHREAD_WIN32_) || defined(__APPLE_CC__) |
| 109 | #define _TTHREAD_EMULATE_CLOCK_GETTIME_ |
| 110 | /* Emulate struct timespec */ |
| 111 | #if defined(_TTHREAD_WIN32_) |
| 112 | struct _ttherad_timespec { |
| 113 | time_t tv_sec; |
| 114 | long tv_nsec; |
| 115 | }; |
| 116 | #define timespec _ttherad_timespec |
| 117 | #endif |
| 118 | |
| 119 | /* Emulate clockid_t */ |
| 120 | typedef int _tthread_clockid_t; |
| 121 | #define clockid_t _tthread_clockid_t |
| 122 | |
| 123 | /* Emulate clock_gettime */ |
| 124 | int _tthread_clock_gettime(clockid_t clk_id, struct timespec *ts); |
| 125 | #define clock_gettime _tthread_clock_gettime |
| 126 | #ifndef CLOCK_REALTIME |
| 127 | #define CLOCK_REALTIME 0 |
| 128 | #endif |
| 129 | #endif |
| 130 | |
| 131 | |
| 132 | /** TinyCThread version (major number). */ |
| 133 | #define TINYCTHREAD_VERSION_MAJOR 1 |
| 134 | /** TinyCThread version (minor number). */ |
| 135 | #define TINYCTHREAD_VERSION_MINOR 1 |
| 136 | /** TinyCThread version (full version). */ |
| 137 | #define TINYCTHREAD_VERSION (TINYCTHREAD_VERSION_MAJOR * 100 + TINYCTHREAD_VERSION_MINOR) |
| 138 | |
| 139 | /** |
| 140 | * @def _Thread_local |
| 141 | * Thread local storage keyword. |
| 142 | * A variable that is declared with the @c _Thread_local keyword makes the |
| 143 | * value of the variable local to each thread (known as thread-local storage, |
| 144 | * or TLS). Example usage: |
| 145 | * @code |
| 146 | * // This variable is local to each thread. |
| 147 | * _Thread_local int variable; |
| 148 | * @endcode |
| 149 | * @note The @c _Thread_local keyword is a macro that maps to the corresponding |
| 150 | * compiler directive (e.g. @c __declspec(thread)). |
| 151 | * @note This directive is currently not supported on Mac OS X (it will give |
| 152 | * a compiler error), since compile-time TLS is not supported in the Mac OS X |
| 153 | * executable format. Also, some older versions of MinGW (before GCC 4.x) do |
| 154 | * not support this directive. |
| 155 | * @hideinitializer |
| 156 | */ |
| 157 | |
| 158 | /* FIXME: Check for a PROPER value of __STDC_VERSION__ to know if we have C11 */ |
| 159 | #if !(defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 201102L)) && !defined(_Thread_local) |
| 160 | #if defined(__GNUC__) || defined(__INTEL_COMPILER) || defined(__SUNPRO_CC) || defined(__IBMCPP__) |
| 161 | #define _Thread_local __thread |
| 162 | #else |
| 163 | #define _Thread_local __declspec(thread) |
| 164 | #endif |
| 165 | #endif |
| 166 | |
| 167 | /* Macros */ |
| 168 | #define TSS_DTOR_ITERATIONS 0 |
| 169 | |
| 170 | /* Function return values */ |
| 171 | #define thrd_error 0 /**< The requested operation failed */ |
| 172 | #define thrd_success 1 /**< The requested operation succeeded */ |
| 173 | #define thrd_timeout 2 /**< The time specified in the call was reached without acquiring the requested resource */ |
| 174 | #define thrd_busy 3 /**< The requested operation failed because a tesource requested by a test and return function is already in use */ |
| 175 | #define thrd_nomem 4 /**< The requested operation failed because it was unable to allocate memory */ |
| 176 | |
| 177 | /* Mutex types */ |
| 178 | #define mtx_plain 1 |
| 179 | #define mtx_timed 2 |
| 180 | #define mtx_try 4 |
| 181 | #define mtx_recursive 8 |
| 182 | |
| 183 | /* Mutex */ |
| 184 | #if defined(_TTHREAD_WIN32_) |
| 185 | typedef struct { |
| 186 | CRITICAL_SECTION mHandle; /* Critical section handle */ |
| 187 | int mAlreadyLocked; /* TRUE if the mutex is already locked */ |
| 188 | int mRecursive; /* TRUE if the mutex is recursive */ |
| 189 | } mtx_t; |
| 190 | #else |
| 191 | typedef pthread_mutex_t mtx_t; |
| 192 | #endif |
| 193 | |
| 194 | /** Create a mutex object. |
| 195 | * @param mtx A mutex object. |
| 196 | * @param type Bit-mask that must have one of the following six values: |
| 197 | * @li @c mtx_plain for a simple non-recursive mutex |
| 198 | * @li @c mtx_timed for a non-recursive mutex that supports timeout |
| 199 | * @li @c mtx_try for a non-recursive mutex that supports test and return |
| 200 | * @li @c mtx_plain | @c mtx_recursive (same as @c mtx_plain, but recursive) |
| 201 | * @li @c mtx_timed | @c mtx_recursive (same as @c mtx_timed, but recursive) |
| 202 | * @li @c mtx_try | @c mtx_recursive (same as @c mtx_try, but recursive) |
| 203 | * @return @ref thrd_success on success, or @ref thrd_error if the request could |
| 204 | * not be honored. |
| 205 | */ |
| 206 | int mtx_init(mtx_t *mtx, int type); |
| 207 | |
| 208 | /** Release any resources used by the given mutex. |
| 209 | * @param mtx A mutex object. |
| 210 | */ |
| 211 | void mtx_destroy(mtx_t *mtx); |
| 212 | |
| 213 | /** Lock the given mutex. |
| 214 | * Blocks until the given mutex can be locked. If the mutex is non-recursive, and |
| 215 | * the calling thread already has a lock on the mutex, this call will block |
| 216 | * forever. |
| 217 | * @param mtx A mutex object. |
| 218 | * @return @ref thrd_success on success, or @ref thrd_error if the request could |
| 219 | * not be honored. |
| 220 | */ |
| 221 | int mtx_lock(mtx_t *mtx); |
| 222 | |
| 223 | /** NOT YET IMPLEMENTED. |
| 224 | */ |
| 225 | int mtx_timedlock(mtx_t *mtx, const struct timespec *ts); |
| 226 | |
| 227 | /** Try to lock the given mutex. |
| 228 | * The specified mutex shall support either test and return or timeout. If the |
| 229 | * mutex is already locked, the function returns without blocking. |
| 230 | * @param mtx A mutex object. |
| 231 | * @return @ref thrd_success on success, or @ref thrd_busy if the resource |
| 232 | * requested is already in use, or @ref thrd_error if the request could not be |
| 233 | * honored. |
| 234 | */ |
| 235 | int mtx_trylock(mtx_t *mtx); |
| 236 | |
| 237 | /** Unlock the given mutex. |
| 238 | * @param mtx A mutex object. |
| 239 | * @return @ref thrd_success on success, or @ref thrd_error if the request could |
| 240 | * not be honored. |
| 241 | */ |
| 242 | int mtx_unlock(mtx_t *mtx); |
| 243 | |
| 244 | /* Condition variable */ |
| 245 | #if defined(_TTHREAD_WIN32_) |
| 246 | typedef struct { |
| 247 | HANDLE mEvents[2]; /* Signal and broadcast event HANDLEs. */ |
| 248 | unsigned int mWaitersCount; /* Count of the number of waiters. */ |
| 249 | CRITICAL_SECTION mWaitersCountLock; /* Serialize access to mWaitersCount. */ |
| 250 | } cnd_t; |
| 251 | #else |
| 252 | typedef pthread_cond_t cnd_t; |
| 253 | #endif |
| 254 | |
| 255 | /** Create a condition variable object. |
| 256 | * @param cond A condition variable object. |
| 257 | * @return @ref thrd_success on success, or @ref thrd_error if the request could |
| 258 | * not be honored. |
| 259 | */ |
| 260 | int cnd_init(cnd_t *cond); |
| 261 | |
| 262 | /** Release any resources used by the given condition variable. |
| 263 | * @param cond A condition variable object. |
| 264 | */ |
| 265 | void cnd_destroy(cnd_t *cond); |
| 266 | |
| 267 | /** Signal a condition variable. |
| 268 | * Unblocks one of the threads that are blocked on the given condition variable |
| 269 | * at the time of the call. If no threads are blocked on the condition variable |
| 270 | * at the time of the call, the function does nothing and return success. |
| 271 | * @param cond A condition variable object. |
| 272 | * @return @ref thrd_success on success, or @ref thrd_error if the request could |
| 273 | * not be honored. |
| 274 | */ |
| 275 | int cnd_signal(cnd_t *cond); |
| 276 | |
| 277 | /** Broadcast a condition variable. |
| 278 | * Unblocks all of the threads that are blocked on the given condition variable |
| 279 | * at the time of the call. If no threads are blocked on the condition variable |
| 280 | * at the time of the call, the function does nothing and return success. |
| 281 | * @param cond A condition variable object. |
| 282 | * @return @ref thrd_success on success, or @ref thrd_error if the request could |
| 283 | * not be honored. |
| 284 | */ |
| 285 | int cnd_broadcast(cnd_t *cond); |
| 286 | |
| 287 | /** Wait for a condition variable to become signaled. |
| 288 | * The function atomically unlocks the given mutex and endeavors to block until |
| 289 | * the given condition variable is signaled by a call to cnd_signal or to |
| 290 | * cnd_broadcast. When the calling thread becomes unblocked it locks the mutex |
| 291 | * before it returns. |
| 292 | * @param cond A condition variable object. |
| 293 | * @param mtx A mutex object. |
| 294 | * @return @ref thrd_success on success, or @ref thrd_error if the request could |
| 295 | * not be honored. |
| 296 | */ |
| 297 | int cnd_wait(cnd_t *cond, mtx_t *mtx); |
| 298 | |
| 299 | /** Wait for a condition variable to become signaled. |
| 300 | * The function atomically unlocks the given mutex and endeavors to block until |
| 301 | * the given condition variable is signaled by a call to cnd_signal or to |
| 302 | * cnd_broadcast, or until after the specified time. When the calling thread |
| 303 | * becomes unblocked it locks the mutex before it returns. |
| 304 | * @param cond A condition variable object. |
| 305 | * @param mtx A mutex object. |
| 306 | * @param xt A point in time at which the request will time out (absolute time). |
| 307 | * @return @ref thrd_success upon success, or @ref thrd_timeout if the time |
| 308 | * specified in the call was reached without acquiring the requested resource, or |
| 309 | * @ref thrd_error if the request could not be honored. |
| 310 | */ |
| 311 | int cnd_timedwait(cnd_t *cond, mtx_t *mtx, const struct timespec *ts); |
| 312 | |
| 313 | /* Thread */ |
| 314 | #if defined(_TTHREAD_WIN32_) |
| 315 | typedef HANDLE thrd_t; |
| 316 | #else |
| 317 | typedef pthread_t thrd_t; |
| 318 | #endif |
| 319 | |
| 320 | /** Thread start function. |
| 321 | * Any thread that is started with the @ref thrd_create() function must be |
| 322 | * started through a function of this type. |
| 323 | * @param arg The thread argument (the @c arg argument of the corresponding |
| 324 | * @ref thrd_create() call). |
| 325 | * @return The thread return value, which can be obtained by another thread |
| 326 | * by using the @ref thrd_join() function. |
| 327 | */ |
| 328 | typedef int (*thrd_start_t)(void *arg); |
| 329 | |
| 330 | /** Create a new thread. |
| 331 | * @param thr Identifier of the newly created thread. |
| 332 | * @param func A function pointer to the function that will be executed in |
| 333 | * the new thread. |
| 334 | * @param arg An argument to the thread function. |
| 335 | * @return @ref thrd_success on success, or @ref thrd_nomem if no memory could |
| 336 | * be allocated for the thread requested, or @ref thrd_error if the request |
| 337 | * could not be honored. |
| 338 | * @note A thread’s identifier may be reused for a different thread once the |
| 339 | * original thread has exited and either been detached or joined to another |
| 340 | * thread. |
| 341 | */ |
| 342 | int thrd_create(thrd_t *thr, thrd_start_t func, void *arg); |
| 343 | |
| 344 | /** Identify the calling thread. |
| 345 | * @return The identifier of the calling thread. |
| 346 | */ |
| 347 | thrd_t thrd_current(void); |
| 348 | |
| 349 | /** NOT YET IMPLEMENTED. |
| 350 | */ |
| 351 | int thrd_detach(thrd_t thr); |
| 352 | |
| 353 | /** Compare two thread identifiers. |
| 354 | * The function determines if two thread identifiers refer to the same thread. |
| 355 | * @return Zero if the two thread identifiers refer to different threads. |
| 356 | * Otherwise a nonzero value is returned. |
| 357 | */ |
| 358 | int thrd_equal(thrd_t thr0, thrd_t thr1); |
| 359 | |
| 360 | /** Terminate execution of the calling thread. |
| 361 | * @param res Result code of the calling thread. |
| 362 | */ |
| 363 | void thrd_exit(int res); |
| 364 | |
| 365 | /** Wait for a thread to terminate. |
| 366 | * The function joins the given thread with the current thread by blocking |
| 367 | * until the other thread has terminated. |
| 368 | * @param thr The thread to join with. |
| 369 | * @param res If this pointer is not NULL, the function will store the result |
| 370 | * code of the given thread in the integer pointed to by @c res. |
| 371 | * @return @ref thrd_success on success, or @ref thrd_error if the request could |
| 372 | * not be honored. |
| 373 | */ |
| 374 | int thrd_join(thrd_t thr, int *res); |
| 375 | |
| 376 | /** Put the calling thread to sleep. |
| 377 | * Suspend execution of the calling thread. |
| 378 | * @param time_point A point in time at which the thread will resume (absolute time). |
| 379 | * @param remaining If non-NULL, this parameter will hold the remaining time until |
| 380 | * time_point upon return. This will typically be zero, but if |
| 381 | * the thread was woken up by a signal that is not ignored before |
| 382 | * time_point was reached @c remaining will hold a positive |
| 383 | * time. |
| 384 | * @return 0 (zero) on successful sleep, or -1 if an interrupt occurred. |
| 385 | */ |
| 386 | int thrd_sleep(const struct timespec *time_point, struct timespec *remaining); |
| 387 | |
| 388 | /** Yield execution to another thread. |
| 389 | * Permit other threads to run, even if the current thread would ordinarily |
| 390 | * continue to run. |
| 391 | */ |
| 392 | void thrd_yield(void); |
| 393 | |
| 394 | /* Thread local storage */ |
| 395 | #if defined(_TTHREAD_WIN32_) |
| 396 | typedef DWORD tss_t; |
| 397 | #else |
| 398 | typedef pthread_key_t tss_t; |
| 399 | #endif |
| 400 | |
| 401 | /** Destructor function for a thread-specific storage. |
| 402 | * @param val The value of the destructed thread-specific storage. |
| 403 | */ |
| 404 | typedef void (*tss_dtor_t)(void *val); |
| 405 | |
| 406 | /** Create a thread-specific storage. |
| 407 | * @param key The unique key identifier that will be set if the function is |
| 408 | * successful. |
| 409 | * @param dtor Destructor function. This can be NULL. |
| 410 | * @return @ref thrd_success on success, or @ref thrd_error if the request could |
| 411 | * not be honored. |
| 412 | * @note The destructor function is not supported under Windows. If @c dtor is |
| 413 | * not NULL when calling this function under Windows, the function will fail |
| 414 | * and return @ref thrd_error. |
| 415 | */ |
| 416 | int tss_create(tss_t *key, tss_dtor_t dtor); |
| 417 | |
| 418 | /** Delete a thread-specific storage. |
| 419 | * The function releases any resources used by the given thread-specific |
| 420 | * storage. |
| 421 | * @param key The key that shall be deleted. |
| 422 | */ |
| 423 | void tss_delete(tss_t key); |
| 424 | |
| 425 | /** Get the value for a thread-specific storage. |
| 426 | * @param key The thread-specific storage identifier. |
| 427 | * @return The value for the current thread held in the given thread-specific |
| 428 | * storage. |
| 429 | */ |
| 430 | void *tss_get(tss_t key); |
| 431 | |
| 432 | /** Set the value for a thread-specific storage. |
| 433 | * @param key The thread-specific storage identifier. |
| 434 | * @param val The value of the thread-specific storage to set for the current |
| 435 | * thread. |
| 436 | * @return @ref thrd_success on success, or @ref thrd_error if the request could |
| 437 | * not be honored. |
| 438 | */ |
| 439 | int tss_set(tss_t key, void *val); |
| 440 | |
| 441 | |
| 442 | #endif /* _TINYTHREAD_H_ */ |
| 443 |