Guido van Rossum | 1984f1e | 1992-08-04 12:41:02 +0000 | [diff] [blame] | 1 | |
Fred Drake | 3cf4d2b | 2000-07-09 00:55:06 +0000 | [diff] [blame] | 2 | #ifndef Py_PYTHREAD_H |
| 3 | #define Py_PYTHREAD_H |
| 4 | |
Guido van Rossum | 65d5b57 | 1998-12-21 19:32:43 +0000 | [diff] [blame] | 5 | typedef void *PyThread_type_lock; |
| 6 | typedef void *PyThread_type_sema; |
Sjoerd Mullender | d10d829 | 1992-09-11 15:19:27 +0000 | [diff] [blame] | 7 | |
| 8 | #ifdef __cplusplus |
| 9 | extern "C" { |
| 10 | #endif |
| 11 | |
Antoine Pitrou | 810023d | 2010-12-15 22:59:16 +0000 | [diff] [blame] | 12 | /* Return status codes for Python lock acquisition. Chosen for maximum |
| 13 | * backwards compatibility, ie failure -> 0, success -> 1. */ |
| 14 | typedef enum PyLockStatus { |
| 15 | PY_LOCK_FAILURE = 0, |
| 16 | PY_LOCK_ACQUIRED = 1, |
| 17 | PY_LOCK_INTR |
| 18 | } PyLockStatus; |
| 19 | |
Serhiy Storchaka | aefa7eb | 2017-03-23 15:48:39 +0200 | [diff] [blame] | 20 | #ifndef Py_LIMITED_API |
| 21 | #define PYTHREAD_INVALID_THREAD_ID ((unsigned long)-1) |
| 22 | #endif |
| 23 | |
Mark Hammond | 91a681d | 2002-08-12 07:21:58 +0000 | [diff] [blame] | 24 | PyAPI_FUNC(void) PyThread_init_thread(void); |
Serhiy Storchaka | aefa7eb | 2017-03-23 15:48:39 +0200 | [diff] [blame] | 25 | PyAPI_FUNC(unsigned long) PyThread_start_new_thread(void (*)(void *), void *); |
Victor Stinner | c664b34 | 2019-05-04 11:48:05 -0400 | [diff] [blame] | 26 | PyAPI_FUNC(void) _Py_NO_RETURN PyThread_exit_thread(void); |
Serhiy Storchaka | aefa7eb | 2017-03-23 15:48:39 +0200 | [diff] [blame] | 27 | PyAPI_FUNC(unsigned long) PyThread_get_thread_ident(void); |
Guido van Rossum | 1984f1e | 1992-08-04 12:41:02 +0000 | [diff] [blame] | 28 | |
Jake Tesler | b121f63 | 2019-05-22 08:43:17 -0700 | [diff] [blame^] | 29 | #if defined(__APPLE__) || defined(__linux__) || defined(__FreeBSD__) || defined(_WIN32) |
| 30 | #define PY_HAVE_THREAD_NATIVE_ID |
| 31 | PyAPI_FUNC(unsigned long) PyThread_get_thread_native_id(void); |
| 32 | #endif |
| 33 | |
Mark Hammond | 91a681d | 2002-08-12 07:21:58 +0000 | [diff] [blame] | 34 | PyAPI_FUNC(PyThread_type_lock) PyThread_allocate_lock(void); |
| 35 | PyAPI_FUNC(void) PyThread_free_lock(PyThread_type_lock); |
| 36 | PyAPI_FUNC(int) PyThread_acquire_lock(PyThread_type_lock, int); |
Masayuki Yamamoto | 731e189 | 2017-10-06 19:41:34 +0900 | [diff] [blame] | 37 | #define WAIT_LOCK 1 |
| 38 | #define NOWAIT_LOCK 0 |
Antoine Pitrou | 7c3e577 | 2010-04-14 15:44:10 +0000 | [diff] [blame] | 39 | |
| 40 | /* PY_TIMEOUT_T is the integral type used to specify timeouts when waiting |
| 41 | on a lock (see PyThread_acquire_lock_timed() below). |
| 42 | PY_TIMEOUT_MAX is the highest usable value (in microseconds) of that |
| 43 | type, and depends on the system threading API. |
Victor Stinner | 754851f | 2011-04-19 23:58:51 +0200 | [diff] [blame] | 44 | |
Antoine Pitrou | 7c3e577 | 2010-04-14 15:44:10 +0000 | [diff] [blame] | 45 | NOTE: this isn't the same value as `_thread.TIMEOUT_MAX`. The _thread |
| 46 | module exposes a higher-level API, with timeouts expressed in seconds |
| 47 | and floating-point numbers allowed. |
| 48 | */ |
Benjamin Peterson | af580df | 2016-09-06 10:46:49 -0700 | [diff] [blame] | 49 | #define PY_TIMEOUT_T long long |
Antoine Pitrou | 7c3e577 | 2010-04-14 15:44:10 +0000 | [diff] [blame] | 50 | |
Victor Stinner | 850a18e | 2017-10-24 16:53:32 -0700 | [diff] [blame] | 51 | #if defined(_POSIX_THREADS) |
| 52 | /* PyThread_acquire_lock_timed() uses _PyTime_FromNanoseconds(us * 1000), |
| 53 | convert microseconds to nanoseconds. */ |
| 54 | # define PY_TIMEOUT_MAX (PY_LLONG_MAX / 1000) |
| 55 | #elif defined (NT_THREADS) |
| 56 | /* In the NT API, the timeout is a DWORD and is expressed in milliseconds */ |
| 57 | # if 0xFFFFFFFFLL * 1000 < PY_LLONG_MAX |
| 58 | # define PY_TIMEOUT_MAX (0xFFFFFFFFLL * 1000) |
| 59 | # else |
| 60 | # define PY_TIMEOUT_MAX PY_LLONG_MAX |
| 61 | # endif |
| 62 | #else |
| 63 | # define PY_TIMEOUT_MAX PY_LLONG_MAX |
Antoine Pitrou | 7c3e577 | 2010-04-14 15:44:10 +0000 | [diff] [blame] | 64 | #endif |
Victor Stinner | 850a18e | 2017-10-24 16:53:32 -0700 | [diff] [blame] | 65 | |
Antoine Pitrou | 7c3e577 | 2010-04-14 15:44:10 +0000 | [diff] [blame] | 66 | |
| 67 | /* If microseconds == 0, the call is non-blocking: it returns immediately |
| 68 | even when the lock can't be acquired. |
| 69 | If microseconds > 0, the call waits up to the specified duration. |
| 70 | If microseconds < 0, the call waits until success (or abnormal failure) |
Antoine Pitrou | 810023d | 2010-12-15 22:59:16 +0000 | [diff] [blame] | 71 | |
Antoine Pitrou | 7c3e577 | 2010-04-14 15:44:10 +0000 | [diff] [blame] | 72 | microseconds must be less than PY_TIMEOUT_MAX. Behaviour otherwise is |
Antoine Pitrou | 810023d | 2010-12-15 22:59:16 +0000 | [diff] [blame] | 73 | undefined. |
| 74 | |
| 75 | If intr_flag is true and the acquire is interrupted by a signal, then the |
| 76 | call will return PY_LOCK_INTR. The caller may reattempt to acquire the |
| 77 | lock. |
| 78 | */ |
| 79 | PyAPI_FUNC(PyLockStatus) PyThread_acquire_lock_timed(PyThread_type_lock, |
| 80 | PY_TIMEOUT_T microseconds, |
| 81 | int intr_flag); |
| 82 | |
Mark Hammond | 91a681d | 2002-08-12 07:21:58 +0000 | [diff] [blame] | 83 | PyAPI_FUNC(void) PyThread_release_lock(PyThread_type_lock); |
Guido van Rossum | 1984f1e | 1992-08-04 12:41:02 +0000 | [diff] [blame] | 84 | |
Thomas Wouters | 0e3f591 | 2006-08-11 14:57:12 +0000 | [diff] [blame] | 85 | PyAPI_FUNC(size_t) PyThread_get_stacksize(void); |
| 86 | PyAPI_FUNC(int) PyThread_set_stacksize(size_t); |
| 87 | |
Serhiy Storchaka | 34d0ac8 | 2016-12-27 14:57:39 +0200 | [diff] [blame] | 88 | #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000 |
Victor Stinner | d5c355c | 2011-04-30 14:53:09 +0200 | [diff] [blame] | 89 | PyAPI_FUNC(PyObject*) PyThread_GetInfo(void); |
Serhiy Storchaka | 34d0ac8 | 2016-12-27 14:57:39 +0200 | [diff] [blame] | 90 | #endif |
Victor Stinner | 754851f | 2011-04-19 23:58:51 +0200 | [diff] [blame] | 91 | |
Masayuki Yamamoto | 731e189 | 2017-10-06 19:41:34 +0900 | [diff] [blame] | 92 | |
| 93 | /* Thread Local Storage (TLS) API |
| 94 | TLS API is DEPRECATED. Use Thread Specific Storage (TSS) API. |
| 95 | |
| 96 | The existing TLS API has used int to represent TLS keys across all |
| 97 | platforms, but it is not POSIX-compliant. Therefore, the new TSS API uses |
| 98 | opaque data type to represent TSS keys to be compatible (see PEP 539). |
| 99 | */ |
| 100 | PyAPI_FUNC(int) PyThread_create_key(void) Py_DEPRECATED(3.7); |
| 101 | PyAPI_FUNC(void) PyThread_delete_key(int key) Py_DEPRECATED(3.7); |
| 102 | PyAPI_FUNC(int) PyThread_set_key_value(int key, void *value) Py_DEPRECATED(3.7); |
| 103 | PyAPI_FUNC(void *) PyThread_get_key_value(int key) Py_DEPRECATED(3.7); |
| 104 | PyAPI_FUNC(void) PyThread_delete_key_value(int key) Py_DEPRECATED(3.7); |
Guido van Rossum | a027efa | 1997-05-05 20:56:21 +0000 | [diff] [blame] | 105 | |
Benjamin Peterson | e68df0f | 2008-06-13 00:26:50 +0000 | [diff] [blame] | 106 | /* Cleanup after a fork */ |
Masayuki Yamamoto | 731e189 | 2017-10-06 19:41:34 +0900 | [diff] [blame] | 107 | PyAPI_FUNC(void) PyThread_ReInitTLS(void) Py_DEPRECATED(3.7); |
| 108 | |
| 109 | |
| 110 | #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03070000 |
| 111 | /* New in 3.7 */ |
| 112 | /* Thread Specific Storage (TSS) API */ |
| 113 | |
| 114 | typedef struct _Py_tss_t Py_tss_t; /* opaque */ |
| 115 | |
| 116 | #ifndef Py_LIMITED_API |
| 117 | #if defined(_POSIX_THREADS) |
| 118 | /* Darwin needs pthread.h to know type name the pthread_key_t. */ |
| 119 | # include <pthread.h> |
| 120 | # define NATIVE_TSS_KEY_T pthread_key_t |
| 121 | #elif defined(NT_THREADS) |
| 122 | /* In Windows, native TSS key type is DWORD, |
| 123 | but hardcode the unsigned long to avoid errors for include directive. |
| 124 | */ |
| 125 | # define NATIVE_TSS_KEY_T unsigned long |
| 126 | #else |
| 127 | # error "Require native threads. See https://bugs.python.org/issue31370" |
| 128 | #endif |
| 129 | |
| 130 | /* When Py_LIMITED_API is not defined, the type layout of Py_tss_t is |
| 131 | exposed to allow static allocation in the API clients. Even in this case, |
| 132 | you must handle TSS keys through API functions due to compatibility. |
| 133 | */ |
| 134 | struct _Py_tss_t { |
| 135 | int _is_initialized; |
| 136 | NATIVE_TSS_KEY_T _key; |
| 137 | }; |
| 138 | |
| 139 | #undef NATIVE_TSS_KEY_T |
| 140 | |
| 141 | /* When static allocation, you must initialize with Py_tss_NEEDS_INIT. */ |
| 142 | #define Py_tss_NEEDS_INIT {0} |
| 143 | #endif /* !Py_LIMITED_API */ |
| 144 | |
| 145 | PyAPI_FUNC(Py_tss_t *) PyThread_tss_alloc(void); |
| 146 | PyAPI_FUNC(void) PyThread_tss_free(Py_tss_t *key); |
| 147 | |
| 148 | /* The parameter key must not be NULL. */ |
| 149 | PyAPI_FUNC(int) PyThread_tss_is_created(Py_tss_t *key); |
| 150 | PyAPI_FUNC(int) PyThread_tss_create(Py_tss_t *key); |
| 151 | PyAPI_FUNC(void) PyThread_tss_delete(Py_tss_t *key); |
| 152 | PyAPI_FUNC(int) PyThread_tss_set(Py_tss_t *key, void *value); |
| 153 | PyAPI_FUNC(void *) PyThread_tss_get(Py_tss_t *key); |
| 154 | #endif /* New in 3.7 */ |
Benjamin Peterson | e68df0f | 2008-06-13 00:26:50 +0000 | [diff] [blame] | 155 | |
Sjoerd Mullender | d10d829 | 1992-09-11 15:19:27 +0000 | [diff] [blame] | 156 | #ifdef __cplusplus |
| 157 | } |
| 158 | #endif |
| 159 | |
Guido van Rossum | d023a78 | 1999-03-24 19:02:09 +0000 | [diff] [blame] | 160 | #endif /* !Py_PYTHREAD_H */ |