1 /* 2 * Copyright (C) 2019 The Android Open Source Project 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * * Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * * Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in 12 * the documentation and/or other materials provided with the 13 * distribution. 14 * 15 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 16 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 17 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 18 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 19 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 20 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 21 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 22 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 23 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 24 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 25 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26 * SUCH DAMAGE. 27 */ 28 29 #pragma once 30 31 /** 32 * @file threads.h 33 * @brief C11 threads. 34 */ 35 36 #include <sys/cdefs.h> 37 38 #include <pthread.h> 39 #include <time.h> 40 41 #define ONCE_FLAG_INIT PTHREAD_ONCE_INIT 42 #define TSS_DTOR_ITERATIONS PTHREAD_DESTRUCTOR_ITERATIONS 43 44 /** The type for a condition variable. */ 45 typedef pthread_cond_t cnd_t; 46 /** The type for a thread. */ 47 typedef pthread_t thrd_t; 48 /** The type for a thread-specific storage key. */ 49 typedef pthread_key_t tss_t; 50 /** The type for a mutex. */ 51 typedef pthread_mutex_t mtx_t; 52 53 /** The type for a thread-specific storage destructor. */ 54 typedef void (*tss_dtor_t)(void* _Nullable); 55 /** The type of the function passed to thrd_create() to create a new thread. */ 56 typedef int (*thrd_start_t)(void* _Nullable); 57 58 /** The type used by call_once(). */ 59 typedef pthread_once_t once_flag; 60 61 enum { 62 mtx_plain = 0x1, 63 mtx_recursive = 0x2, 64 mtx_timed = 0x4, 65 }; 66 67 enum { 68 thrd_success = 0, 69 thrd_busy = 1, 70 thrd_error = 2, 71 thrd_nomem = 3, 72 thrd_timedout = 4, 73 }; 74 75 /* `thread_local` is a keyword in C++11 and C23; C11 had `_Thread_local` instead. */ 76 #if !defined(__cplusplus) && (__STDC_VERSION__ >= 201112L && __STDC_VERSION__ < 202311L) 77 # undef thread_local 78 # define thread_local _Thread_local 79 #endif 80 81 __BEGIN_DECLS 82 83 #if __ANDROID_API__ >= 30 84 // This file is implemented as static inlines before API level 30. 85 86 /** Uses `__flag` to ensure that `__function` is called exactly once. */ 87 void call_once(once_flag* _Nonnull __flag, void (* _Nonnull __function)(void)) __INTRODUCED_IN(30); 88 89 90 91 /** 92 * Unblocks all threads blocked on `__cond`. 93 */ 94 int cnd_broadcast(cnd_t* _Nonnull __cond) __INTRODUCED_IN(30); 95 96 /** 97 * Destroys a condition variable. 98 */ 99 void cnd_destroy(cnd_t* _Nonnull __cond) __INTRODUCED_IN(30); 100 101 /** 102 * Creates a condition variable. 103 */ 104 int cnd_init(cnd_t* _Nonnull __cond) __INTRODUCED_IN(30); 105 106 /** 107 * Unblocks one thread blocked on `__cond`. 108 */ 109 int cnd_signal(cnd_t* _Nonnull __cond) __INTRODUCED_IN(30); 110 111 /** 112 * Unlocks `__mutex` and blocks until `__cond` is signaled or `__timeout` occurs. 113 */ 114 int cnd_timedwait(cnd_t* _Nonnull __cond, mtx_t* _Nonnull __mutex, const struct timespec* _Nonnull __timeout) 115 __INTRODUCED_IN(30); 116 117 /** 118 * Unlocks `__mutex` and blocks until `__cond` is signaled. 119 */ 120 int cnd_wait(cnd_t* _Nonnull __cond, mtx_t* _Nonnull __mutex) __INTRODUCED_IN(30); 121 122 123 124 /** 125 * Destroys a mutex. 126 */ 127 void mtx_destroy(mtx_t* _Nonnull __mutex) __INTRODUCED_IN(30); 128 129 /** 130 * Creates a mutex. 131 */ 132 int mtx_init(mtx_t* _Nonnull __mutex, int __type) __INTRODUCED_IN(30); 133 134 /** 135 * Blocks until `__mutex` is acquired. 136 */ 137 int mtx_lock(mtx_t* _Nonnull __mutex) __INTRODUCED_IN(30); 138 139 /** 140 * Blocks until `__mutex` is acquired or `__timeout` expires. 141 */ 142 int mtx_timedlock(mtx_t* _Nonnull __mutex, const struct timespec* _Nonnull __timeout) __INTRODUCED_IN(30); 143 144 /** 145 * Acquires `__mutex` or returns `thrd_busy`. 146 */ 147 int mtx_trylock(mtx_t* _Nonnull __mutex) __INTRODUCED_IN(30); 148 149 /** 150 * Unlocks `__mutex`. 151 */ 152 int mtx_unlock(mtx_t* _Nonnull __mutex) __INTRODUCED_IN(30); 153 154 155 156 /** 157 * Creates a new thread running `__function(__arg)`, and sets `*__thrd` to 158 * the new thread. 159 */ 160 int thrd_create(thrd_t* _Nonnull __thrd, thrd_start_t _Nonnull __function, void* _Nullable __arg) __INTRODUCED_IN(30); 161 162 /** 163 * Returns the `thrd_t` corresponding to the caller. 164 */ 165 thrd_t thrd_current(void) __INTRODUCED_IN(30); 166 167 /** 168 * Tells the OS to automatically dispose of `__thrd` when it exits. 169 */ 170 int thrd_detach(thrd_t __thrd) __INTRODUCED_IN(30); 171 172 /** 173 * Tests whether two threads are the same thread. 174 */ 175 int thrd_equal(thrd_t __lhs, thrd_t __rhs) __INTRODUCED_IN(30); 176 177 /** 178 * Terminates the calling thread, setting its result to `__result`. 179 */ 180 void thrd_exit(int __result) __noreturn __INTRODUCED_IN(30); 181 182 /** 183 * Blocks until `__thrd` terminates. If `__result` is not null, `*__result` 184 * is set to the exiting thread's result. 185 */ 186 int thrd_join(thrd_t __thrd, int* _Nullable __result) __INTRODUCED_IN(30); 187 188 /** 189 * Blocks the caller for at least `__duration` unless a signal is delivered. 190 * If a signal causes the sleep to end early and `__remaining` is not null, 191 * `*__remaining` is set to the time remaining. 192 * 193 * Returns 0 on success, or -1 if a signal was delivered. 194 */ 195 int thrd_sleep(const struct timespec* _Nonnull __duration, struct timespec* _Nullable __remaining) __INTRODUCED_IN(30); 196 197 /** 198 * Request that other threads should be scheduled. 199 */ 200 void thrd_yield(void) __INTRODUCED_IN(30); 201 202 203 204 /** 205 * Creates a thread-specific storage key with the associated destructor (which 206 * may be null). 207 */ 208 int tss_create(tss_t* _Nonnull __key, tss_dtor_t _Nullable __dtor) __INTRODUCED_IN(30); 209 210 /** 211 * Destroys a thread-specific storage key. 212 */ 213 void tss_delete(tss_t __key) __INTRODUCED_IN(30); 214 215 /** 216 * Returns the value for the current thread held in the thread-specific storage 217 * identified by `__key`. 218 */ 219 void* _Nullable tss_get(tss_t __key) __INTRODUCED_IN(30); 220 221 /** 222 * Sets the current thread's value for the thread-specific storage identified 223 * by `__key` to `__value`. 224 */ 225 int tss_set(tss_t __key, void* _Nonnull __value) __INTRODUCED_IN(30); 226 227 #endif 228 229 __END_DECLS 230 231 #include <android/legacy_threads_inlines.h> 232