|
| 1 | +/* Macros that restrict available definitions and select implementations |
| 2 | + * to match an ABI stability promise: |
| 3 | + * |
| 4 | + * - internal API/ABI (may change at any time) -- Py_BUILD_CORE* |
| 5 | + * - general CPython API/ABI (may change in 3.x.0) -- default |
| 6 | + * - Stable ABI: abi3, abi3t (long-term stable) -- Py_LIMITED_API, |
| 7 | + * Py_TARGET_ABI3T, _Py_OPAQUE_PYOBJECT |
| 8 | + * - Free-threading (incompatible with non-free-threading builds) |
| 9 | + * -- Py_GIL_DISABLED |
| 10 | + */ |
| 11 | + |
| 12 | +#ifndef _Py_PYABI_H |
| 13 | +#define _Py_PYABI_H |
| 14 | + |
| 15 | +/* Defines to build Python and its standard library: |
| 16 | + * |
| 17 | + * - Py_BUILD_CORE: Build Python core. Give access to Python internals, but |
| 18 | + * should not be used by third-party modules. |
| 19 | + * - Py_BUILD_CORE_BUILTIN: Build a Python stdlib module as a built-in module. |
| 20 | + * - Py_BUILD_CORE_MODULE: Build a Python stdlib module as a dynamic library. |
| 21 | + * |
| 22 | + * Py_BUILD_CORE_BUILTIN and Py_BUILD_CORE_MODULE imply Py_BUILD_CORE. |
| 23 | + * |
| 24 | + * On Windows, Py_BUILD_CORE_MODULE exports "PyInit_xxx" symbol, whereas |
| 25 | + * Py_BUILD_CORE_BUILTIN does not. |
| 26 | + */ |
| 27 | +#if defined(Py_BUILD_CORE_BUILTIN) && !defined(Py_BUILD_CORE) |
| 28 | +# define Py_BUILD_CORE |
| 29 | +#endif |
| 30 | +#if defined(Py_BUILD_CORE_MODULE) && !defined(Py_BUILD_CORE) |
| 31 | +# define Py_BUILD_CORE |
| 32 | +#endif |
| 33 | + |
| 34 | +/* Stable ABI for free-threaded builds (abi3t, introduced in PEP 803) |
| 35 | + is enabled by the user setting one of: |
| 36 | + - Py_TARGET_ABI3T, or |
| 37 | + - Py_LIMITED_API and Py_GIL_DISABLED. |
| 38 | +
|
| 39 | + These affect set the following, which Python.h should use internally: |
| 40 | + - Py_LIMITED_API (defines the subset of API we expose) |
| 41 | + - _Py_OPAQUE_PYOBJECT (additionally hides what's ABI-incompatible between |
| 42 | + free-threaded & GIL) |
| 43 | +
|
| 44 | + (Don't use Py_TARGET_ABI3T directly. It's currently only used to set these |
| 45 | + 2 macro, and defined for users' convenience.) |
| 46 | + */ |
| 47 | +#if defined(Py_LIMITED_API) && defined(Py_GIL_DISABLED) \ |
| 48 | + && !defined(Py_TARGET_ABI3T) |
| 49 | +# define Py_TARGET_ABI3T Py_LIMITED_API |
| 50 | +#endif |
| 51 | +#if defined(Py_TARGET_ABI3T) |
| 52 | +# define _Py_OPAQUE_PYOBJECT |
| 53 | +# if !defined(Py_LIMITED_API) |
| 54 | +# define Py_LIMITED_API Py_TARGET_ABI3T |
| 55 | +# elif Py_LIMITED_API > Py_TARGET_ABI3T |
| 56 | + // if both are defined, use the *lower* version, |
| 57 | + // i.e. maximum compatibility |
| 58 | +# undef Py_LIMITED_API |
| 59 | +# define Py_LIMITED_API Py_TARGET_ABI3T |
| 60 | +# endif |
| 61 | +#endif |
| 62 | + |
| 63 | +#if defined(Py_TARGET_ABI3T) |
| 64 | +# if !defined(Py_GIL_DISABLED) |
| 65 | +// Define Py_GIL_DISABLED for users' needs. Users check this macro to see |
| 66 | +// whether they need extra synchronization. |
| 67 | +# define Py_GIL_DISABLED |
| 68 | +# endif |
| 69 | +# if defined(_Py_IS_TESTCEXT) |
| 70 | +// When compiling for abi3t, contents of Python.h should not depend |
| 71 | +// on Py_GIL_DISABLED. |
| 72 | +// We ask GCC to error if it sees the macro from this point on. |
| 73 | +// Since users are free to the macro, and there's no way to undo the poisoning |
| 74 | +// at the end of Python.h, we only do this in a test module. |
| 75 | +# ifdef __GNUC__ |
| 76 | +# undef Py_GIL_DISABLED |
| 77 | +# pragma GCC poison Py_GIL_DISABLED |
| 78 | +# endif |
| 79 | +# endif |
| 80 | +#endif |
| 81 | + |
| 82 | +#endif // _Py_PYABI_H |
0 commit comments