pyo3/types/
capsule.rs

1use crate::ffi_ptr_ext::FfiPtrExt;
2use crate::py_result_ext::PyResultExt;
3use crate::{ffi, PyAny};
4use crate::{Bound, Python};
5use crate::{PyErr, PyResult};
6use std::ffi::{CStr, CString};
7use std::os::raw::{c_char, c_int, c_void};
8/// Represents a Python Capsule
9/// as described in [Capsules](https://docs.python.org/3/c-api/capsule.html#capsules):
10/// > This subtype of PyObject represents an opaque value, useful for C extension
11/// > modules who need to pass an opaque value (as a void* pointer) through Python
12/// > code to other C code. It is often used to make a C function pointer defined
13/// > in one module available to other modules, so the regular import mechanism can
14/// > be used to access C APIs defined in dynamically loaded modules.
15///
16/// Values of this type are accessed via PyO3's smart pointers, e.g. as
17/// [`Py<PyCapsule>`][crate::Py] or [`Bound<'py, PyCapsule>`][Bound].
18///
19/// For APIs available on capsule objects, see the [`PyCapsuleMethods`] trait which is implemented for
20/// [`Bound<'py, PyCapsule>`][Bound].
21///
22/// # Example
23/// ```
24/// use pyo3::{prelude::*, types::PyCapsule};
25/// use std::ffi::CString;
26///
27/// #[repr(C)]
28/// struct Foo {
29///     pub val: u32,
30/// }
31///
32/// let r = Python::with_gil(|py| -> PyResult<()> {
33///     let foo = Foo { val: 123 };
34///     let name = CString::new("builtins.capsule").unwrap();
35///
36///     let capsule = PyCapsule::new(py, foo, Some(name.clone()))?;
37///
38///     let module = PyModule::import(py, "builtins")?;
39///     module.add("capsule", capsule)?;
40///
41///     let cap: &Foo = unsafe { PyCapsule::import(py, name.as_ref())? };
42///     assert_eq!(cap.val, 123);
43///     Ok(())
44/// });
45/// assert!(r.is_ok());
46/// ```
47#[repr(transparent)]
48pub struct PyCapsule(PyAny);
49
50pyobject_native_type_core!(PyCapsule, pyobject_native_static_type_object!(ffi::PyCapsule_Type), #checkfunction=ffi::PyCapsule_CheckExact);
51
52impl PyCapsule {
53    /// Constructs a new capsule whose contents are `value`, associated with `name`.
54    /// `name` is the identifier for the capsule; if it is stored as an attribute of a module,
55    /// the name should be in the format `"modulename.attribute"`.
56    ///
57    /// It is checked at compile time that the type T is not zero-sized. Rust function items
58    /// need to be cast to a function pointer (`fn(args) -> result`) to be put into a capsule.
59    ///
60    /// # Example
61    ///
62    /// ```
63    /// use pyo3::{prelude::*, types::PyCapsule};
64    /// use std::ffi::CString;
65    ///
66    /// Python::with_gil(|py| {
67    ///     let name = CString::new("foo").unwrap();
68    ///     let capsule = PyCapsule::new(py, 123_u32, Some(name)).unwrap();
69    ///     let val = unsafe { capsule.reference::<u32>() };
70    ///     assert_eq!(*val, 123);
71    /// });
72    /// ```
73    ///
74    /// However, attempting to construct a `PyCapsule` with a zero-sized type will not compile:
75    ///
76    /// ```compile_fail
77    /// use pyo3::{prelude::*, types::PyCapsule};
78    /// use std::ffi::CString;
79    ///
80    /// Python::with_gil(|py| {
81    ///     let capsule = PyCapsule::new(py, (), None).unwrap();  // Oops! `()` is zero sized!
82    /// });
83    /// ```
84    pub fn new<T: 'static + Send + AssertNotZeroSized>(
85        py: Python<'_>,
86        value: T,
87        name: Option<CString>,
88    ) -> PyResult<Bound<'_, Self>> {
89        Self::new_with_destructor(py, value, name, |_, _| {})
90    }
91
92    /// Constructs a new capsule whose contents are `value`, associated with `name`.
93    ///
94    /// Also provides a destructor: when the `PyCapsule` is destroyed, it will be passed the original object,
95    /// as well as a `*mut c_void` which will point to the capsule's context, if any.
96    ///
97    /// The `destructor` must be `Send`, because there is no guarantee which thread it will eventually
98    /// be called from.
99    pub fn new_with_destructor<
100        T: 'static + Send + AssertNotZeroSized,
101        F: FnOnce(T, *mut c_void) + Send,
102    >(
103        py: Python<'_>,
104        value: T,
105        name: Option<CString>,
106        destructor: F,
107    ) -> PyResult<Bound<'_, Self>> {
108        AssertNotZeroSized::assert_not_zero_sized(&value);
109
110        // Sanity check for capsule layout
111        debug_assert_eq!(memoffset::offset_of!(CapsuleContents::<T, F>, value), 0);
112
113        let name_ptr = name.as_ref().map_or(std::ptr::null(), |name| name.as_ptr());
114        let val = Box::new(CapsuleContents {
115            value,
116            destructor,
117            name,
118        });
119
120        unsafe {
121            ffi::PyCapsule_New(
122                Box::into_raw(val).cast(),
123                name_ptr,
124                Some(capsule_destructor::<T, F>),
125            )
126            .assume_owned_or_err(py)
127            .downcast_into_unchecked()
128        }
129    }
130
131    /// Imports an existing capsule.
132    ///
133    /// The `name` should match the path to the module attribute exactly in the form
134    /// of `"module.attribute"`, which should be the same as the name within the capsule.
135    ///
136    /// # Safety
137    ///
138    /// It must be known that the capsule imported by `name` contains an item of type `T`.
139    pub unsafe fn import<'py, T>(py: Python<'py>, name: &CStr) -> PyResult<&'py T> {
140        let ptr = unsafe { ffi::PyCapsule_Import(name.as_ptr(), false as c_int) };
141        if ptr.is_null() {
142            Err(PyErr::fetch(py))
143        } else {
144            Ok(unsafe { &*ptr.cast::<T>() })
145        }
146    }
147}
148
149/// Implementation of functionality for [`PyCapsule`].
150///
151/// These methods are defined for the `Bound<'py, PyCapsule>` smart pointer, so to use method call
152/// syntax these methods are separated into a trait, because stable Rust does not yet support
153/// `arbitrary_self_types`.
154#[doc(alias = "PyCapsule")]
155pub trait PyCapsuleMethods<'py>: crate::sealed::Sealed {
156    /// Sets the context pointer in the capsule.
157    ///
158    /// Returns an error if this capsule is not valid.
159    ///
160    /// # Notes
161    ///
162    /// The context is treated much like the value of the capsule, but should likely act as
163    /// a place to store any state management when using the capsule.
164    ///
165    /// If you want to store a Rust value as the context, and drop it from the destructor, use
166    /// `Box::into_raw` to convert it into a pointer, see the example.
167    ///
168    /// # Example
169    ///
170    /// ```
171    /// use std::os::raw::c_void;
172    /// use std::sync::mpsc::{channel, Sender};
173    /// use pyo3::{prelude::*, types::PyCapsule};
174    ///
175    /// let (tx, rx) = channel::<String>();
176    ///
177    /// fn destructor(val: u32, context: *mut c_void) {
178    ///     let ctx = unsafe { *Box::from_raw(context.cast::<Sender<String>>()) };
179    ///     ctx.send("Destructor called!".to_string()).unwrap();
180    /// }
181    ///
182    /// Python::with_gil(|py| {
183    ///     let capsule =
184    ///         PyCapsule::new_with_destructor(py, 123, None, destructor as fn(u32, *mut c_void))
185    ///             .unwrap();
186    ///     let context = Box::new(tx);  // `Sender<String>` is our context, box it up and ship it!
187    ///     capsule.set_context(Box::into_raw(context).cast()).unwrap();
188    ///     // This scope will end, causing our destructor to be called...
189    /// });
190    ///
191    /// assert_eq!(rx.recv(), Ok("Destructor called!".to_string()));
192    /// ```
193    fn set_context(&self, context: *mut c_void) -> PyResult<()>;
194
195    /// Gets the current context stored in the capsule. If there is no context, the pointer
196    /// will be null.
197    ///
198    /// Returns an error if this capsule is not valid.
199    fn context(&self) -> PyResult<*mut c_void>;
200
201    /// Obtains a reference to the value of this capsule.
202    ///
203    /// # Safety
204    ///
205    /// It must be known that this capsule is valid and its pointer is to an item of type `T`.
206    unsafe fn reference<T>(&self) -> &'py T;
207
208    /// Gets the raw `c_void` pointer to the value in this capsule.
209    ///
210    /// Returns null if this capsule is not valid.
211    fn pointer(&self) -> *mut c_void;
212
213    /// Checks if this is a valid capsule.
214    ///
215    /// Returns true if the stored `pointer()` is non-null.
216    fn is_valid(&self) -> bool;
217
218    /// Retrieves the name of this capsule, if set.
219    ///
220    /// Returns an error if this capsule is not valid.
221    fn name(&self) -> PyResult<Option<&'py CStr>>;
222}
223
224impl<'py> PyCapsuleMethods<'py> for Bound<'py, PyCapsule> {
225    #[allow(clippy::not_unsafe_ptr_arg_deref)]
226    fn set_context(&self, context: *mut c_void) -> PyResult<()> {
227        let result = unsafe { ffi::PyCapsule_SetContext(self.as_ptr(), context) };
228        if result != 0 {
229            Err(PyErr::fetch(self.py()))
230        } else {
231            Ok(())
232        }
233    }
234
235    fn context(&self) -> PyResult<*mut c_void> {
236        let ctx = unsafe { ffi::PyCapsule_GetContext(self.as_ptr()) };
237        if ctx.is_null() {
238            ensure_no_error(self.py())?
239        }
240        Ok(ctx)
241    }
242
243    unsafe fn reference<T>(&self) -> &'py T {
244        unsafe { &*self.pointer().cast() }
245    }
246
247    fn pointer(&self) -> *mut c_void {
248        unsafe {
249            let ptr = ffi::PyCapsule_GetPointer(self.as_ptr(), name_ptr_ignore_error(self));
250            if ptr.is_null() {
251                ffi::PyErr_Clear();
252            }
253            ptr
254        }
255    }
256
257    fn is_valid(&self) -> bool {
258        // As well as if the stored pointer is null, PyCapsule_IsValid also returns false if
259        // self.as_ptr() is null or not a ptr to a PyCapsule object. Both of these are guaranteed
260        // to not be the case thanks to invariants of this PyCapsule struct.
261        let r = unsafe { ffi::PyCapsule_IsValid(self.as_ptr(), name_ptr_ignore_error(self)) };
262        r != 0
263    }
264
265    fn name(&self) -> PyResult<Option<&'py CStr>> {
266        unsafe {
267            let ptr = ffi::PyCapsule_GetName(self.as_ptr());
268            if ptr.is_null() {
269                ensure_no_error(self.py())?;
270                Ok(None)
271            } else {
272                Ok(Some(CStr::from_ptr(ptr)))
273            }
274        }
275    }
276}
277
278// C layout, as PyCapsule::get_reference depends on `T` being first.
279#[repr(C)]
280struct CapsuleContents<T: 'static + Send, D: FnOnce(T, *mut c_void) + Send> {
281    /// Value of the capsule
282    value: T,
283    /// Destructor to be used by the capsule
284    destructor: D,
285    /// Name used when creating the capsule
286    name: Option<CString>,
287}
288
289// Wrapping ffi::PyCapsule_Destructor for a user supplied FnOnce(T) for capsule destructor
290unsafe extern "C" fn capsule_destructor<T: 'static + Send, F: FnOnce(T, *mut c_void) + Send>(
291    capsule: *mut ffi::PyObject,
292) {
293    unsafe {
294        let ptr = ffi::PyCapsule_GetPointer(capsule, ffi::PyCapsule_GetName(capsule));
295        let ctx = ffi::PyCapsule_GetContext(capsule);
296        let CapsuleContents {
297            value, destructor, ..
298        } = *Box::from_raw(ptr.cast::<CapsuleContents<T, F>>());
299        destructor(value, ctx)
300    }
301}
302
303/// Guarantee `T` is not zero sized at compile time.
304// credit: `<https://users.rust-lang.org/t/is-it-possible-to-assert-at-compile-time-that-foo-t-is-not-called-with-a-zst/67685>`
305#[doc(hidden)]
306pub trait AssertNotZeroSized: Sized {
307    const _CONDITION: usize = (std::mem::size_of::<Self>() == 0) as usize;
308    const _CHECK: &'static str =
309        ["PyCapsule value type T must not be zero-sized!"][Self::_CONDITION];
310    #[allow(path_statements, clippy::no_effect)]
311    fn assert_not_zero_sized(&self) {
312        <Self as AssertNotZeroSized>::_CHECK;
313    }
314}
315
316impl<T> AssertNotZeroSized for T {}
317
318fn ensure_no_error(py: Python<'_>) -> PyResult<()> {
319    if let Some(err) = PyErr::take(py) {
320        Err(err)
321    } else {
322        Ok(())
323    }
324}
325
326fn name_ptr_ignore_error(slf: &Bound<'_, PyCapsule>) -> *const c_char {
327    let ptr = unsafe { ffi::PyCapsule_GetName(slf.as_ptr()) };
328    if ptr.is_null() {
329        unsafe { ffi::PyErr_Clear() };
330    }
331    ptr
332}
333
334#[cfg(test)]
335mod tests {
336    use crate::prelude::PyModule;
337    use crate::types::capsule::PyCapsuleMethods;
338    use crate::types::module::PyModuleMethods;
339    use crate::{types::PyCapsule, Py, PyResult, Python};
340    use std::ffi::CString;
341    use std::os::raw::c_void;
342    use std::sync::mpsc::{channel, Sender};
343
344    #[test]
345    fn test_pycapsule_struct() -> PyResult<()> {
346        #[repr(C)]
347        struct Foo {
348            pub val: u32,
349        }
350
351        impl Foo {
352            fn get_val(&self) -> u32 {
353                self.val
354            }
355        }
356
357        Python::with_gil(|py| -> PyResult<()> {
358            let foo = Foo { val: 123 };
359            let name = CString::new("foo").unwrap();
360
361            let cap = PyCapsule::new(py, foo, Some(name.clone()))?;
362            assert!(cap.is_valid());
363
364            let foo_capi = unsafe { cap.reference::<Foo>() };
365            assert_eq!(foo_capi.val, 123);
366            assert_eq!(foo_capi.get_val(), 123);
367            assert_eq!(cap.name().unwrap(), Some(name.as_ref()));
368            Ok(())
369        })
370    }
371
372    #[test]
373    fn test_pycapsule_func() {
374        fn foo(x: u32) -> u32 {
375            x
376        }
377
378        let cap: Py<PyCapsule> = Python::with_gil(|py| {
379            let name = CString::new("foo").unwrap();
380            let cap = PyCapsule::new(py, foo as fn(u32) -> u32, Some(name)).unwrap();
381            cap.into()
382        });
383
384        Python::with_gil(move |py| {
385            let f = unsafe { cap.bind(py).reference::<fn(u32) -> u32>() };
386            assert_eq!(f(123), 123);
387        });
388    }
389
390    #[test]
391    fn test_pycapsule_context() -> PyResult<()> {
392        Python::with_gil(|py| {
393            let name = CString::new("foo").unwrap();
394            let cap = PyCapsule::new(py, 0, Some(name))?;
395
396            let c = cap.context()?;
397            assert!(c.is_null());
398
399            let ctx = Box::new(123_u32);
400            cap.set_context(Box::into_raw(ctx).cast())?;
401
402            let ctx_ptr: *mut c_void = cap.context()?;
403            let ctx = unsafe { *Box::from_raw(ctx_ptr.cast::<u32>()) };
404            assert_eq!(ctx, 123);
405            Ok(())
406        })
407    }
408
409    #[test]
410    fn test_pycapsule_import() -> PyResult<()> {
411        #[repr(C)]
412        struct Foo {
413            pub val: u32,
414        }
415
416        Python::with_gil(|py| -> PyResult<()> {
417            let foo = Foo { val: 123 };
418            let name = CString::new("builtins.capsule").unwrap();
419
420            let capsule = PyCapsule::new(py, foo, Some(name.clone()))?;
421
422            let module = PyModule::import(py, "builtins")?;
423            module.add("capsule", capsule)?;
424
425            // check error when wrong named passed for capsule.
426            let wrong_name = CString::new("builtins.non_existant").unwrap();
427            let result: PyResult<&Foo> = unsafe { PyCapsule::import(py, wrong_name.as_ref()) };
428            assert!(result.is_err());
429
430            // corret name is okay.
431            let cap: &Foo = unsafe { PyCapsule::import(py, name.as_ref())? };
432            assert_eq!(cap.val, 123);
433            Ok(())
434        })
435    }
436
437    #[test]
438    fn test_vec_storage() {
439        let cap: Py<PyCapsule> = Python::with_gil(|py| {
440            let name = CString::new("foo").unwrap();
441
442            let stuff: Vec<u8> = vec![1, 2, 3, 4];
443            let cap = PyCapsule::new(py, stuff, Some(name)).unwrap();
444
445            cap.into()
446        });
447
448        Python::with_gil(move |py| {
449            let ctx: &Vec<u8> = unsafe { cap.bind(py).reference() };
450            assert_eq!(ctx, &[1, 2, 3, 4]);
451        })
452    }
453
454    #[test]
455    fn test_vec_context() {
456        let context: Vec<u8> = vec![1, 2, 3, 4];
457
458        let cap: Py<PyCapsule> = Python::with_gil(|py| {
459            let name = CString::new("foo").unwrap();
460            let cap = PyCapsule::new(py, 0, Some(name)).unwrap();
461            cap.set_context(Box::into_raw(Box::new(&context)).cast())
462                .unwrap();
463
464            cap.into()
465        });
466
467        Python::with_gil(move |py| {
468            let ctx_ptr: *mut c_void = cap.bind(py).context().unwrap();
469            let ctx = unsafe { *Box::from_raw(ctx_ptr.cast::<&Vec<u8>>()) };
470            assert_eq!(ctx, &vec![1_u8, 2, 3, 4]);
471        })
472    }
473
474    #[test]
475    fn test_pycapsule_destructor() {
476        let (tx, rx) = channel::<bool>();
477
478        fn destructor(_val: u32, ctx: *mut c_void) {
479            assert!(!ctx.is_null());
480            let context = unsafe { *Box::from_raw(ctx.cast::<Sender<bool>>()) };
481            context.send(true).unwrap();
482        }
483
484        Python::with_gil(move |py| {
485            let name = CString::new("foo").unwrap();
486            let cap = PyCapsule::new_with_destructor(py, 0, Some(name), destructor).unwrap();
487            cap.set_context(Box::into_raw(Box::new(tx)).cast()).unwrap();
488        });
489
490        // the destructor was called.
491        assert_eq!(rx.recv(), Ok(true));
492    }
493
494    #[test]
495    fn test_pycapsule_no_name() {
496        Python::with_gil(|py| {
497            let cap = PyCapsule::new(py, 0usize, None).unwrap();
498
499            assert_eq!(unsafe { cap.reference::<usize>() }, &0usize);
500            assert_eq!(cap.name().unwrap(), None);
501            assert_eq!(cap.context().unwrap(), std::ptr::null_mut());
502        });
503    }
504}
pyo3/types/capsule.rs

pyo3/types/
capsule.rs
