feat(ffi): add Python 3.14 context watcher API

newsfragments/6204.added.md

@@ -0,0 +1 @@
+Add FFI definitions `PyContext_AddWatcher` and `PyContext_ClearWatcher` on Python 3.14+.

pyo3-ffi/src/context.rs → pyo3-ffi/src/cpython/context.rs

@@ -1,11 +1,10 @@
 use crate::object::PyObject;
-#[cfg(not(RustPython))]
 use crate::object::PyTypeObject;
-#[cfg(not(RustPython))]
 use crate::Py_IS_TYPE;
+#[cfg(all(Py_3_14, not(any(PyPy, GraalPy))))]
+use core::ffi::c_uint;
 use core::ffi::{c_char, c_int};
 
-#[cfg(not(RustPython))]
 extern_libpython! {
     pub static mut PyContext_Type: PyTypeObject;
     // skipped non-limited opaque PyContext
@@ -16,37 +15,45 @@ extern_libpython! {
 }
 
 #[inline]
-#[cfg(not(RustPython))]
 pub unsafe fn PyContext_CheckExact(op: *mut PyObject) -> c_int {
     Py_IS_TYPE(op, &raw mut PyContext_Type)
 }
 
 #[inline]
-#[cfg(not(RustPython))]
 pub unsafe fn PyContextVar_CheckExact(op: *mut PyObject) -> c_int {
     Py_IS_TYPE(op, &raw mut PyContextVar_Type)
 }
 
 #[inline]
-#[cfg(not(RustPython))]
 pub unsafe fn PyContextToken_CheckExact(op: *mut PyObject) -> c_int {
     Py_IS_TYPE(op, &raw mut PyContextToken_Type)
 }
 
 extern_libpython! {
-    #[cfg(RustPython)]
-    pub fn PyContext_CheckExact(op: *mut PyObject) -> c_int;
-    #[cfg(RustPython)]
-    pub fn PyContextVar_CheckExact(op: *mut PyObject) -> c_int;
-    #[cfg(RustPython)]
-    pub fn PyContextToken_CheckExact(op: *mut PyObject) -> c_int;
-
     pub fn PyContext_New() -> *mut PyObject;
     pub fn PyContext_Copy(ctx: *mut PyObject) -> *mut PyObject;
     pub fn PyContext_CopyCurrent() -> *mut PyObject;
 
     pub fn PyContext_Enter(ctx: *mut PyObject) -> c_int;
     pub fn PyContext_Exit(ctx: *mut PyObject) -> c_int;
+}
+
+// Use the C enum's integer representation to permit future event values.
+#[cfg(all(Py_3_14, not(any(PyPy, GraalPy))))]
+pub type PyContextEvent = c_uint;
+
+#[cfg(all(Py_3_14, not(any(PyPy, GraalPy))))]
+pub const Py_CONTEXT_SWITCHED: PyContextEvent = 1;
+
+#[cfg(all(Py_3_14, not(any(PyPy, GraalPy))))]
+pub type PyContext_WatchCallback =
+    unsafe extern "C" fn(event: PyContextEvent, obj: *mut PyObject) -> c_int;
+
+extern_libpython! {
+    #[cfg(all(Py_3_14, not(any(PyPy, GraalPy))))]
+    pub fn PyContext_AddWatcher(callback: PyContext_WatchCallback) -> c_int;
+    #[cfg(all(Py_3_14, not(any(PyPy, GraalPy))))]
+    pub fn PyContext_ClearWatcher(watcher_id: c_int) -> c_int;
 
     pub fn PyContextVar_New(name: *const c_char, def: *mut PyObject) -> *mut PyObject;
     pub fn PyContextVar_Get(

pyo3-ffi/src/cpython/mod.rs

@@ -7,6 +7,7 @@ pub(crate) mod ceval;
 pub(crate) mod code;
 pub(crate) mod compile;
 pub(crate) mod complexobject;
+pub(crate) mod context;
 #[cfg(all(Py_3_14, Py_GIL_DISABLED))]
 pub(crate) mod critical_section;
 pub(crate) mod descrobject;
@@ -56,6 +57,7 @@ pub use self::ceval::*;
 pub use self::code::*;
 pub use self::compile::*;
 pub use self::complexobject::*;
+pub use self::context::*;
 #[cfg(all(Py_3_14, Py_GIL_DISABLED))]
 pub use self::critical_section::{PyCriticalSection2_BeginMutex, PyCriticalSection_BeginMutex};
 pub use self::descrobject::*;

pyo3-ffi/src/lib.rs

@@ -446,8 +446,6 @@ pub use self::ceval::*;
 pub use self::codecs::*;
 pub use self::compile::*;
 pub use self::complexobject::*;
-#[cfg(not(Py_LIMITED_API))]
-pub use self::context::*;
 #[cfg(Py_3_13)]
 pub use self::critical_section::*;
 #[cfg(not(Py_LIMITED_API))]
@@ -516,8 +514,6 @@ mod ceval;
 mod codecs;
 mod compile;
 mod complexobject;
-#[cfg(not(Py_LIMITED_API))]
-mod context;
 mod critical_section;
 #[cfg(not(Py_LIMITED_API))]
 pub(crate) mod datetime;