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