• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 
2 #ifndef Py_PYTHREAD_H
3 #define Py_PYTHREAD_H
4 
5 typedef void *PyThread_type_lock;
6 typedef void *PyThread_type_sema;
7 
8 #ifdef __cplusplus
9 extern "C" {
10 #endif
11 
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 
20 #ifndef Py_LIMITED_API
21 #define PYTHREAD_INVALID_THREAD_ID ((unsigned long)-1)
22 #endif
23 
24 PyAPI_FUNC(void) PyThread_init_thread(void);
25 PyAPI_FUNC(unsigned long) PyThread_start_new_thread(void (*)(void *), void *);
26 PyAPI_FUNC(void) PyThread_exit_thread(void);
27 PyAPI_FUNC(unsigned long) PyThread_get_thread_ident(void);
28 
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);
32 #define WAIT_LOCK       1
33 #define NOWAIT_LOCK     0
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.
39 
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 */
44 #define PY_TIMEOUT_T long long
45 
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
59 #endif
60 
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)
66 
67    microseconds must be less than PY_TIMEOUT_MAX. Behaviour otherwise is
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 
78 PyAPI_FUNC(void) PyThread_release_lock(PyThread_type_lock);
79 
80 PyAPI_FUNC(size_t) PyThread_get_stacksize(void);
81 PyAPI_FUNC(int) PyThread_set_stacksize(size_t);
82 
83 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000
84 PyAPI_FUNC(PyObject*) PyThread_GetInfo(void);
85 #endif
86 
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);
100 
101 /* Cleanup after a fork */
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 */
150 
151 #ifdef __cplusplus
152 }
153 #endif
154 
155 #endif /* !Py_PYTHREAD_H */
156