/opt/imh/python3.13/include/python3.13/internal
Edit: /opt/imh/python3.13/include/python3.13/internal/pycore_parking_lot.h (3351B)
// ParkingLot is an internal API for building efficient synchronization
// primitives like mutexes and events.
//
// The API and name is inspired by WebKit's WTF::ParkingLot, which in turn
// is inspired Linux's futex API.
// See https://webkit.org/blog/6161/locking-in-webkit/.
//
// The core functionality is an atomic "compare-and-sleep" operation along with
// an atomic "wake-up" operation.
#ifndef Py_INTERNAL_PARKING_LOT_H
#define Py_INTERNAL_PARKING_LOT_H
#ifdef __cplusplus
extern "C" {
#endif
#ifndef Py_BUILD_CORE
# error "this header requires Py_BUILD_CORE define"
#endif
enum {
// The thread was unparked by another thread.
Py_PARK_OK = 0,
// The value of `address` did not match `expected`.
Py_PARK_AGAIN = -1,
// The thread was unparked due to a timeout.
Py_PARK_TIMEOUT = -2,
// The thread was interrupted by a signal.
Py_PARK_INTR = -3,
};
// Checks that `*address == *expected` and puts the thread to sleep until an
// unpark operation is called on the same `address`. Otherwise, the function
// returns `Py_PARK_AGAIN`. The comparison behaves like memcmp, but is
// performed atomically with respect to unpark operations.
//
// The `address_size` argument is the size of the data pointed to by the
// `address` and `expected` pointers (i.e., sizeof(*address)). It must be
// 1, 2, 4, or 8.
//
// The `timeout_ns` argument specifies the maximum amount of time to wait, with
// -1 indicating an infinite wait.
//
// `park_arg`, which can be NULL, is passed to the unpark operation.
//
// If `detach` is true, then the thread will detach/release the GIL while
// waiting.
//
// Example usage:
//
// if (_Py_atomic_compare_exchange_uint8(address, &expected, new_value)) {
// int res = _PyParkingLot_Park(address, &new_value, sizeof(*address),
// timeout_ns, NULL, 1);
// ...
// }
PyAPI_FUNC(int)
_PyParkingLot_Park(const void *address, const void *expected,
size_t address_size, PyTime_t timeout_ns,
void *park_arg, int detach);
// Callback for _PyParkingLot_Unpark:
//
// `arg` is the data of the same name provided to the _PyParkingLot_Unpark()
// call.
// `park_arg` is the data provided to _PyParkingLot_Park() call or NULL if
// no waiting thread was found.
// `has_more_waiters` is true if there are more threads waiting on the same
// address. May be true in cases where threads are waiting on a different
// address that map to the same internal bucket.
typedef void _Py_unpark_fn_t(void *arg, void *park_arg, int has_more_waiters);
// Unparks a single thread waiting on `address`.
//
// Note that fn() is called regardless of whether a thread was unparked. If
// no threads are waiting on `address` then the `park_arg` argument to fn()
// will be NULL.
//
// Example usage:
// void callback(void *arg, void *park_arg, int has_more_waiters);
// _PyParkingLot_Unpark(address, &callback, arg);
PyAPI_FUNC(void)
_PyParkingLot_Unpark(const void *address, _Py_unpark_fn_t *fn, void *arg);
// Unparks all threads waiting on `address`.
PyAPI_FUNC(void) _PyParkingLot_UnparkAll(const void *address);
// Resets the parking lot state after a fork. Forgets all parked threads.
PyAPI_FUNC(void) _PyParkingLot_AfterFork(void);
#ifdef __cplusplus
}
#endif
#endif /* !Py_INTERNAL_PARKING_LOT_H */