include/python3.12/pythread.h

0001 #ifndef Py_PYTHREAD_H
0002 #define Py_PYTHREAD_H
0003
0004 typedef void *PyThread_type_lock;
0005
0006 #ifdef __cplusplus
0007 extern "C" {
0008 #endif
0009
0010 /* Return status codes for Python lock acquisition.  Chosen for maximum
0011  * backwards compatibility, ie failure -> 0, success -> 1.  */
0012 typedef enum PyLockStatus {
0013     PY_LOCK_FAILURE = 0,
0014     PY_LOCK_ACQUIRED = 1,
0015     PY_LOCK_INTR
0016 } PyLockStatus;
0017
0018 PyAPI_FUNC(void) PyThread_init_thread(void);
0019 PyAPI_FUNC(unsigned long) PyThread_start_new_thread(void (*)(void *), void *);
0020 PyAPI_FUNC(void) _Py_NO_RETURN PyThread_exit_thread(void);
0021 PyAPI_FUNC(unsigned long) PyThread_get_thread_ident(void);
0022
0023 #if (defined(__APPLE__) || defined(__linux__) || defined(_WIN32) \
0024      || defined(__FreeBSD__) || defined(__OpenBSD__) || defined(__NetBSD__) \
0025      || defined(__DragonFly__) || defined(_AIX))
0026 #define PY_HAVE_THREAD_NATIVE_ID
0027 PyAPI_FUNC(unsigned long) PyThread_get_thread_native_id(void);
0028 #endif
0029
0030 PyAPI_FUNC(PyThread_type_lock) PyThread_allocate_lock(void);
0031 PyAPI_FUNC(void) PyThread_free_lock(PyThread_type_lock);
0032 PyAPI_FUNC(int) PyThread_acquire_lock(PyThread_type_lock, int);
0033 #define WAIT_LOCK       1
0034 #define NOWAIT_LOCK     0
0035
0036 /* PY_TIMEOUT_T is the integral type used to specify timeouts when waiting
0037    on a lock (see PyThread_acquire_lock_timed() below).
0038    PY_TIMEOUT_MAX is the highest usable value (in microseconds) of that
0039    type, and depends on the system threading API.
0040
0041    NOTE: this isn't the same value as `_thread.TIMEOUT_MAX`.  The _thread
0042    module exposes a higher-level API, with timeouts expressed in seconds
0043    and floating-point numbers allowed.
0044 */
0045 #define PY_TIMEOUT_T long long
0046
0047 #if defined(_POSIX_THREADS)
0048    /* PyThread_acquire_lock_timed() uses _PyTime_FromNanoseconds(us * 1000),
0049       convert microseconds to nanoseconds. */
0050 #  define PY_TIMEOUT_MAX (LLONG_MAX / 1000)
0051 #elif defined (NT_THREADS)
0052    // WaitForSingleObject() accepts timeout in milliseconds in the range
0053    // [0; 0xFFFFFFFE] (DWORD type). INFINITE value (0xFFFFFFFF) means no
0054    // timeout. 0xFFFFFFFE milliseconds is around 49.7 days.
0055 #  if 0xFFFFFFFELL * 1000 < LLONG_MAX
0056 #    define PY_TIMEOUT_MAX (0xFFFFFFFELL * 1000)
0057 #  else
0058 #    define PY_TIMEOUT_MAX LLONG_MAX
0059 #  endif
0060 #else
0061 #  define PY_TIMEOUT_MAX LLONG_MAX
0062 #endif
0063
0064
0065 /* If microseconds == 0, the call is non-blocking: it returns immediately
0066    even when the lock can't be acquired.
0067    If microseconds > 0, the call waits up to the specified duration.
0068    If microseconds < 0, the call waits until success (or abnormal failure)
0069
0070    microseconds must be less than PY_TIMEOUT_MAX. Behaviour otherwise is
0071    undefined.
0072
0073    If intr_flag is true and the acquire is interrupted by a signal, then the
0074    call will return PY_LOCK_INTR.  The caller may reattempt to acquire the
0075    lock.
0076 */
0077 PyAPI_FUNC(PyLockStatus) PyThread_acquire_lock_timed(PyThread_type_lock,
0078                                                      PY_TIMEOUT_T microseconds,
0079                                                      int intr_flag);
0080
0081 PyAPI_FUNC(void) PyThread_release_lock(PyThread_type_lock);
0082
0083 PyAPI_FUNC(size_t) PyThread_get_stacksize(void);
0084 PyAPI_FUNC(int) PyThread_set_stacksize(size_t);
0085
0086 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000
0087 PyAPI_FUNC(PyObject*) PyThread_GetInfo(void);
0088 #endif
0089
0090
0091 /* Thread Local Storage (TLS) API
0092    TLS API is DEPRECATED.  Use Thread Specific Storage (TSS) API.
0093
0094    The existing TLS API has used int to represent TLS keys across all
0095    platforms, but it is not POSIX-compliant.  Therefore, the new TSS API uses
0096    opaque data type to represent TSS keys to be compatible (see PEP 539).
0097 */
0098 Py_DEPRECATED(3.7) PyAPI_FUNC(int) PyThread_create_key(void);
0099 Py_DEPRECATED(3.7) PyAPI_FUNC(void) PyThread_delete_key(int key);
0100 Py_DEPRECATED(3.7) PyAPI_FUNC(int) PyThread_set_key_value(int key,
0101                                                           void *value);
0102 Py_DEPRECATED(3.7) PyAPI_FUNC(void *) PyThread_get_key_value(int key);
0103 Py_DEPRECATED(3.7) PyAPI_FUNC(void) PyThread_delete_key_value(int key);
0104
0105 /* Cleanup after a fork */
0106 Py_DEPRECATED(3.7) PyAPI_FUNC(void) PyThread_ReInitTLS(void);
0107
0108
0109 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03070000
0110 /* New in 3.7 */
0111 /* Thread Specific Storage (TSS) API */
0112
0113 typedef struct _Py_tss_t Py_tss_t;  /* opaque */
0114
0115 PyAPI_FUNC(Py_tss_t *) PyThread_tss_alloc(void);
0116 PyAPI_FUNC(void) PyThread_tss_free(Py_tss_t *key);
0117
0118 /* The parameter key must not be NULL. */
0119 PyAPI_FUNC(int) PyThread_tss_is_created(Py_tss_t *key);
0120 PyAPI_FUNC(int) PyThread_tss_create(Py_tss_t *key);
0121 PyAPI_FUNC(void) PyThread_tss_delete(Py_tss_t *key);
0122 PyAPI_FUNC(int) PyThread_tss_set(Py_tss_t *key, void *value);
0123 PyAPI_FUNC(void *) PyThread_tss_get(Py_tss_t *key);
0124 #endif  /* New in 3.7 */
0125
0126 #ifndef Py_LIMITED_API
0127 #  define Py_CPYTHON_PYTHREAD_H
0128 #  include "cpython/pythread.h"
0129 #  undef Py_CPYTHON_PYTHREAD_H
0130 #endif
0131
0132 #ifdef __cplusplus
0133 }
0134 #endif
0135 #endif /* !Py_PYTHREAD_H */