pyo3/
ffi_ptr_ext.rs

1use crate::sealed::Sealed;
2use crate::{
3    ffi,
4    instance::{Borrowed, Bound},
5    PyAny, PyResult, Python,
6};
7
8pub(crate) trait FfiPtrExt: Sealed {
9    /// Assumes this pointer carries a Python reference which needs to be decref'd.
10    ///
11    /// If the pointer is NULL, this function will fetch an error.
12    unsafe fn assume_owned_or_err(self, py: Python<'_>) -> PyResult<Bound<'_, PyAny>>;
13
14    /// Same as `assume_owned_or_err`, but doesn't fetch an error on NULL.
15    unsafe fn assume_owned_or_opt(self, py: Python<'_>) -> Option<Bound<'_, PyAny>>;
16
17    /// Same as `assume_owned_or_err`, but panics on NULL.
18    unsafe fn assume_owned(self, py: Python<'_>) -> Bound<'_, PyAny>;
19
20    /// Same as `assume_owned_or_err`, but does not check for NULL.
21    unsafe fn assume_owned_unchecked(self, py: Python<'_>) -> Bound<'_, PyAny>;
22
23    /// Assumes this pointer is borrowed from a parent object.
24    ///
25    /// Warning: the lifetime `'a` is not bounded by the function arguments; the caller is
26    /// responsible to ensure this is tied to some appropriate lifetime.
27    unsafe fn assume_borrowed_or_err<'a>(self, py: Python<'_>)
28        -> PyResult<Borrowed<'a, '_, PyAny>>;
29
30    /// Same as `assume_borrowed_or_err`, but doesn't fetch an error on NULL.
31    unsafe fn assume_borrowed_or_opt<'a>(self, py: Python<'_>) -> Option<Borrowed<'a, '_, PyAny>>;
32
33    /// Same as `assume_borrowed_or_err`, but panics on NULL.
34    unsafe fn assume_borrowed<'a>(self, py: Python<'_>) -> Borrowed<'a, '_, PyAny>;
35
36    /// Same as `assume_borrowed_or_err`, but does not check for NULL.
37    unsafe fn assume_borrowed_unchecked<'a>(self, py: Python<'_>) -> Borrowed<'a, '_, PyAny>;
38}
39
40impl FfiPtrExt for *mut ffi::PyObject {
41    /// # Safety
42    ///
43    /// see requirements for [`Bound::from_owned_ptr_or_err`]
44    #[inline]
45    unsafe fn assume_owned_or_err(self, py: Python<'_>) -> PyResult<Bound<'_, PyAny>> {
46        // SAFETY: caller upholds requirements
47        unsafe { Bound::from_owned_ptr_or_err(py, self) }
48    }
49
50    /// # Safety
51    ///
52    /// see requirements for [`Bound::from_owned_ptr_or_opt`]
53    #[inline]
54    unsafe fn assume_owned_or_opt(self, py: Python<'_>) -> Option<Bound<'_, PyAny>> {
55        // SAFETY: caller upholds requirements
56        unsafe { Bound::from_owned_ptr_or_opt(py, self) }
57    }
58
59    /// # Safety
60    ///
61    /// see requirements for [`Bound::from_owned_ptr`]
62    #[inline]
63    #[track_caller]
64    unsafe fn assume_owned(self, py: Python<'_>) -> Bound<'_, PyAny> {
65        // SAFETY: caller upholds requirements
66        unsafe { Bound::from_owned_ptr(py, self) }
67    }
68
69    /// # Safety
70    ///
71    /// see requirements for [`Bound::from_owned_ptr_unchecked`]
72    #[inline]
73    unsafe fn assume_owned_unchecked(self, py: Python<'_>) -> Bound<'_, PyAny> {
74        // SAFETY: caller upholds requirements
75        unsafe { Bound::from_owned_ptr_unchecked(py, self) }
76    }
77
78    /// # Safety
79    ///
80    /// see requirements for [`Borrowed::from_ptr_or_err`]
81    #[inline]
82    unsafe fn assume_borrowed_or_err<'a>(
83        self,
84        py: Python<'_>,
85    ) -> PyResult<Borrowed<'a, '_, PyAny>> {
86        // SAFETY: caller upholds requirements
87        unsafe { Borrowed::from_ptr_or_err(py, self) }
88    }
89
90    /// # Safety
91    ///
92    /// see requirements for [`Borrowed::from_ptr_or_opt`]
93    #[inline]
94    unsafe fn assume_borrowed_or_opt<'a>(self, py: Python<'_>) -> Option<Borrowed<'a, '_, PyAny>> {
95        // SAFETY: caller upholds requirements
96        unsafe { Borrowed::from_ptr_or_opt(py, self) }
97    }
98
99    /// # Safety
100    ///
101    /// see requirements for [`Borrowed::from_ptr`]
102    #[inline]
103    #[track_caller]
104    unsafe fn assume_borrowed<'a>(self, py: Python<'_>) -> Borrowed<'a, '_, PyAny> {
105        // SAFETY: caller upholds requirements
106        unsafe { Borrowed::from_ptr(py, self) }
107    }
108
109    /// # Safety
110    ///
111    /// see requirements for [`Borrowed::from_ptr_unchecked`]
112    #[inline]
113    unsafe fn assume_borrowed_unchecked<'a>(self, py: Python<'_>) -> Borrowed<'a, '_, PyAny> {
114        // SAFETY: caller upholds requirements
115        unsafe { Borrowed::from_ptr_unchecked(py, self) }
116    }
117}
pyo3/ffi_ptr_ext.rs

pyo3/
ffi_ptr_ext.rs
