ref_sharing.rs
523 lines
| 16.5 KiB
| application/rls-services+xml
|
RustLexer
|
r43352 | // ref_sharing.rs | ||
|
r42997 | // | ||
// Copyright 2019 Raphaël Gomès <rgomes@octobus.net> | ||||
// | ||||
|
r43352 | // Permission is hereby granted, free of charge, to any person obtaining a copy | ||
// of this software and associated documentation files (the "Software"), to | ||||
// deal in the Software without restriction, including without limitation the | ||||
// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or | ||||
// sell copies of the Software, and to permit persons to whom the Software is | ||||
// furnished to do so, subject to the following conditions: | ||||
// | ||||
// The above copyright notice and this permission notice shall be included in | ||||
// all copies or substantial portions of the Software. | ||||
// | ||||
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | ||||
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | ||||
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | ||||
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | ||||
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING | ||||
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS | ||||
// IN THE SOFTWARE. | ||||
|
r42997 | |||
//! Macros for use in the `hg-cpython` bridge library. | ||||
use crate::exceptions::AlreadyBorrowed; | ||||
|
r43447 | use cpython::{PyClone, PyObject, PyResult, Python}; | ||
|
r43115 | use std::cell::{Cell, Ref, RefCell, RefMut}; | ||
|
r42997 | |||
/// Manages the shared state between Python and Rust | ||||
|
r43443 | #[derive(Debug, Default)] | ||
|
r43582 | struct PySharedState { | ||
|
r42997 | leak_count: Cell<usize>, | ||
mutably_borrowed: Cell<bool>, | ||||
} | ||||
|
r43445 | // &PySharedState can be Send because any access to inner cells is | ||
// synchronized by the GIL. | ||||
unsafe impl Sync for PySharedState {} | ||||
|
r42997 | impl PySharedState { | ||
|
r43582 | fn borrow_mut<'a, T>( | ||
|
r42997 | &'a self, | ||
py: Python<'a>, | ||||
pyrefmut: RefMut<'a, T>, | ||||
) -> PyResult<PyRefMut<'a, T>> { | ||||
if self.mutably_borrowed.get() { | ||||
return Err(AlreadyBorrowed::new( | ||||
py, | ||||
"Cannot borrow mutably while there exists another \ | ||||
mutable reference in a Python object", | ||||
)); | ||||
} | ||||
match self.leak_count.get() { | ||||
0 => { | ||||
self.mutably_borrowed.replace(true); | ||||
Ok(PyRefMut::new(py, pyrefmut, self)) | ||||
} | ||||
// TODO | ||||
// For now, this works differently than Python references | ||||
// in the case of iterators. | ||||
// Python does not complain when the data an iterator | ||||
// points to is modified if the iterator is never used | ||||
// afterwards. | ||||
// Here, we are stricter than this by refusing to give a | ||||
// mutable reference if it is already borrowed. | ||||
// While the additional safety might be argued for, it | ||||
// breaks valid programming patterns in Python and we need | ||||
// to fix this issue down the line. | ||||
_ => Err(AlreadyBorrowed::new( | ||||
py, | ||||
"Cannot borrow mutably while there are \ | ||||
immutable references in Python objects", | ||||
)), | ||||
} | ||||
} | ||||
|
r43446 | /// Return a reference to the wrapped data and its state with an | ||
/// artificial static lifetime. | ||||
|
r42997 | /// We need to be protected by the GIL for thread-safety. | ||
|
r43117 | /// | ||
/// # Safety | ||||
/// | ||||
/// This is highly unsafe since the lifetime of the given data can be | ||||
/// extended. Do not call this function directly. | ||||
|
r43582 | unsafe fn leak_immutable<T>( | ||
|
r42997 | &self, | ||
py: Python, | ||||
|
r43115 | data: &PySharedRefCell<T>, | ||
|
r43446 | ) -> PyResult<(&'static T, &'static PySharedState)> { | ||
|
r42997 | if self.mutably_borrowed.get() { | ||
return Err(AlreadyBorrowed::new( | ||||
py, | ||||
"Cannot borrow immutably while there is a \ | ||||
mutable reference in Python objects", | ||||
)); | ||||
} | ||||
|
r43446 | // TODO: it's weird that self is data.py_shared_state. Maybe we | ||
// can move stuff to PySharedRefCell? | ||||
|
r42997 | let ptr = data.as_ptr(); | ||
|
r43446 | let state_ptr: *const PySharedState = &data.py_shared_state; | ||
|
r42997 | self.leak_count.replace(self.leak_count.get() + 1); | ||
|
r43446 | Ok((&*ptr, &*state_ptr)) | ||
|
r42997 | } | ||
|
r43117 | /// # Safety | ||
/// | ||||
|
r43582 | /// It's up to you to make sure the reference is about to be deleted | ||
/// when updating the leak count. | ||||
fn decrease_leak_count(&self, _py: Python, mutable: bool) { | ||||
|
r42997 | if mutable { | ||
|
r43209 | assert_eq!(self.leak_count.get(), 0); | ||
assert!(self.mutably_borrowed.get()); | ||||
|
r42997 | self.mutably_borrowed.replace(false); | ||
|
r43209 | } else { | ||
let count = self.leak_count.get(); | ||||
assert!(count > 0); | ||||
self.leak_count.replace(count - 1); | ||||
|
r42997 | } | ||
} | ||||
} | ||||
|
r43115 | /// `RefCell` wrapper to be safely used in conjunction with `PySharedState`. | ||
/// | ||||
|
r43582 | /// This object can be stored in a `py_class!` object as a data field. Any | ||
/// operation is allowed through the `PySharedRef` interface. | ||||
|
r43115 | #[derive(Debug)] | ||
pub struct PySharedRefCell<T> { | ||||
inner: RefCell<T>, | ||||
|
r43448 | py_shared_state: PySharedState, | ||
|
r43115 | } | ||
impl<T> PySharedRefCell<T> { | ||||
|
r43443 | pub fn new(value: T) -> PySharedRefCell<T> { | ||
|
r43115 | Self { | ||
inner: RefCell::new(value), | ||||
|
r43443 | py_shared_state: PySharedState::default(), | ||
|
r43115 | } | ||
} | ||||
|
r43582 | fn borrow<'a>(&'a self, _py: Python<'a>) -> Ref<'a, T> { | ||
|
r43115 | // py_shared_state isn't involved since | ||
// - inner.borrow() would fail if self is mutably borrowed, | ||||
// - and inner.borrow_mut() would fail while self is borrowed. | ||||
self.inner.borrow() | ||||
} | ||||
|
r43582 | fn as_ptr(&self) -> *mut T { | ||
|
r43115 | self.inner.as_ptr() | ||
} | ||||
|
r43444 | // TODO: maybe this should be named as try_borrow_mut(), and use | ||
// inner.try_borrow_mut(). The current implementation panics if | ||||
// self.inner has been borrowed, but returns error if py_shared_state | ||||
// refuses to borrow. | ||||
|
r43582 | fn borrow_mut<'a>(&'a self, py: Python<'a>) -> PyResult<PyRefMut<'a, T>> { | ||
|
r43444 | self.py_shared_state.borrow_mut(py, self.inner.borrow_mut()) | ||
|
r43115 | } | ||
} | ||||
|
r43448 | /// Sharable data member of type `T` borrowed from the `PyObject`. | ||
pub struct PySharedRef<'a, T> { | ||||
py: Python<'a>, | ||||
owner: &'a PyObject, | ||||
data: &'a PySharedRefCell<T>, | ||||
} | ||||
impl<'a, T> PySharedRef<'a, T> { | ||||
/// # Safety | ||||
/// | ||||
/// The `data` must be owned by the `owner`. Otherwise, the leak count | ||||
/// would get wrong. | ||||
pub unsafe fn new( | ||||
py: Python<'a>, | ||||
owner: &'a PyObject, | ||||
data: &'a PySharedRefCell<T>, | ||||
) -> Self { | ||||
Self { py, owner, data } | ||||
} | ||||
|
r43566 | pub fn borrow(&self) -> Ref<'a, T> { | ||
|
r43580 | self.data.borrow(self.py) | ||
|
r43448 | } | ||
pub fn borrow_mut(&self) -> PyResult<PyRefMut<'a, T>> { | ||||
self.data.borrow_mut(self.py) | ||||
} | ||||
|
r43579 | /// Returns a leaked reference. | ||
|
r43603 | pub fn leak_immutable(&self) -> PyResult<PyLeaked<&'static T>> { | ||
|
r43579 | let state = &self.data.py_shared_state; | ||
unsafe { | ||||
let (static_ref, static_state_ref) = | ||||
state.leak_immutable(self.py, self.data)?; | ||||
|
r43603 | Ok(PyLeaked::new( | ||
|
r43579 | self.py, | ||
self.owner, | ||||
static_ref, | ||||
static_state_ref, | ||||
)) | ||||
} | ||||
|
r43448 | } | ||
} | ||||
|
r42997 | /// Holds a mutable reference to data shared between Python and Rust. | ||
pub struct PyRefMut<'a, T> { | ||||
|
r43581 | py: Python<'a>, | ||
|
r42997 | inner: RefMut<'a, T>, | ||
py_shared_state: &'a PySharedState, | ||||
} | ||||
impl<'a, T> PyRefMut<'a, T> { | ||||
|
r43117 | // Must be constructed by PySharedState after checking its leak_count. | ||
// Otherwise, drop() would incorrectly update the state. | ||||
|
r42997 | fn new( | ||
|
r43581 | py: Python<'a>, | ||
|
r42997 | inner: RefMut<'a, T>, | ||
py_shared_state: &'a PySharedState, | ||||
) -> Self { | ||||
Self { | ||||
|
r43581 | py, | ||
|
r42997 | inner, | ||
py_shared_state, | ||||
} | ||||
} | ||||
} | ||||
impl<'a, T> std::ops::Deref for PyRefMut<'a, T> { | ||||
type Target = RefMut<'a, T>; | ||||
fn deref(&self) -> &Self::Target { | ||||
&self.inner | ||||
} | ||||
} | ||||
impl<'a, T> std::ops::DerefMut for PyRefMut<'a, T> { | ||||
fn deref_mut(&mut self) -> &mut Self::Target { | ||||
&mut self.inner | ||||
} | ||||
} | ||||
impl<'a, T> Drop for PyRefMut<'a, T> { | ||||
fn drop(&mut self) { | ||||
|
r43582 | self.py_shared_state.decrease_leak_count(self.py, true); | ||
|
r42997 | } | ||
} | ||||
/// Allows a `py_class!` generated struct to share references to one of its | ||||
/// data members with Python. | ||||
/// | ||||
/// # Warning | ||||
/// | ||||
/// TODO allow Python container types: for now, integration with the garbage | ||||
/// collector does not extend to Rust structs holding references to Python | ||||
/// objects. Should the need surface, `__traverse__` and `__clear__` will | ||||
/// need to be written as per the `rust-cpython` docs on GC integration. | ||||
/// | ||||
/// # Parameters | ||||
/// | ||||
/// * `$name` is the same identifier used in for `py_class!` macro call. | ||||
/// * `$inner_struct` is the identifier of the underlying Rust struct | ||||
/// * `$data_member` is the identifier of the data member of `$inner_struct` | ||||
/// that will be shared. | ||||
|
r43448 | /// * `$shared_accessor` is the function name to be generated, which allows | ||
/// safe access to the data member. | ||||
/// | ||||
/// # Safety | ||||
/// | ||||
/// `$data_member` must persist while the `$name` object is alive. In other | ||||
/// words, it must be an accessor to a data field of the Python object. | ||||
|
r42997 | /// | ||
/// # Example | ||||
/// | ||||
/// ``` | ||||
/// struct MyStruct { | ||||
/// inner: Vec<u32>; | ||||
/// } | ||||
/// | ||||
/// py_class!(pub class MyType |py| { | ||||
|
r43115 | /// data inner: PySharedRefCell<MyStruct>; | ||
|
r42997 | /// }); | ||
/// | ||||
|
r43448 | /// py_shared_ref!(MyType, MyStruct, inner, inner_shared); | ||
|
r42997 | /// ``` | ||
macro_rules! py_shared_ref { | ||||
( | ||||
$name: ident, | ||||
$inner_struct: ident, | ||||
|
r43448 | $data_member: ident, | ||
$shared_accessor: ident | ||||
|
r42997 | ) => { | ||
impl $name { | ||||
|
r43448 | /// Returns a safe reference to the shared `$data_member`. | ||
/// | ||||
/// This function guarantees that `PySharedRef` is created with | ||||
/// the valid `self` and `self.$data_member(py)` pair. | ||||
fn $shared_accessor<'a>( | ||||
&'a self, | ||||
py: Python<'a>, | ||||
) -> $crate::ref_sharing::PySharedRef<'a, $inner_struct> { | ||||
use cpython::PythonObject; | ||||
use $crate::ref_sharing::PySharedRef; | ||||
let owner = self.as_object(); | ||||
let data = self.$data_member(py); | ||||
unsafe { PySharedRef::new(py, owner, data) } | ||||
} | ||||
|
r42997 | } | ||
|
r43447 | }; | ||
} | ||||
|
r42997 | |||
|
r43447 | /// Manage immutable references to `PyObject` leaked into Python iterators. | ||
|
r43603 | pub struct PyLeaked<T> { | ||
|
r43579 | inner: PyObject, | ||
data: Option<T>, | ||||
|
r43447 | py_shared_state: &'static PySharedState, | ||
} | ||||
|
r42997 | |||
|
r43603 | // DO NOT implement Deref for PyLeaked<T>! Dereferencing PyLeaked | ||
|
r43579 | // without taking Python GIL wouldn't be safe. | ||
|
r43603 | impl<T> PyLeaked<T> { | ||
|
r43447 | /// # Safety | ||
/// | ||||
/// The `py_shared_state` must be owned by the `inner` Python object. | ||||
|
r43582 | fn new( | ||
|
r43447 | py: Python, | ||
inner: &PyObject, | ||||
|
r43578 | data: T, | ||
|
r43447 | py_shared_state: &'static PySharedState, | ||
) -> Self { | ||||
Self { | ||||
|
r43579 | inner: inner.clone_ref(py), | ||
|
r43578 | data: Some(data), | ||
|
r43447 | py_shared_state, | ||
|
r42997 | } | ||
|
r43447 | } | ||
|
r43579 | |||
/// Returns an immutable reference to the inner value. | ||||
pub fn get_ref<'a>(&'a self, _py: Python<'a>) -> &'a T { | ||||
self.data.as_ref().unwrap() | ||||
} | ||||
/// Returns a mutable reference to the inner value. | ||||
/// | ||||
/// Typically `T` is an iterator. If `T` is an immutable reference, | ||||
/// `get_mut()` is useless since the inner value can't be mutated. | ||||
pub fn get_mut<'a>(&'a mut self, _py: Python<'a>) -> &'a mut T { | ||||
self.data.as_mut().unwrap() | ||||
} | ||||
/// Converts the inner value by the given function. | ||||
/// | ||||
/// Typically `T` is a static reference to a container, and `U` is an | ||||
/// iterator of that container. | ||||
/// | ||||
/// # Safety | ||||
/// | ||||
/// The lifetime of the object passed in to the function `f` is cheated. | ||||
/// It's typically a static reference, but is valid only while the | ||||
|
r43603 | /// corresponding `PyLeaked` is alive. Do not copy it out of the | ||
|
r43579 | /// function call. | ||
pub unsafe fn map<U>( | ||||
mut self, | ||||
py: Python, | ||||
f: impl FnOnce(T) -> U, | ||||
|
r43603 | ) -> PyLeaked<U> { | ||
|
r43579 | // f() could make the self.data outlive. That's why map() is unsafe. | ||
// In order to make this function safe, maybe we'll need a way to | ||||
// temporarily restrict the lifetime of self.data and translate the | ||||
// returned object back to Something<'static>. | ||||
let new_data = f(self.data.take().unwrap()); | ||||
|
r43603 | PyLeaked { | ||
|
r43579 | inner: self.inner.clone_ref(py), | ||
data: Some(new_data), | ||||
py_shared_state: self.py_shared_state, | ||||
} | ||||
} | ||||
|
r43447 | } | ||
|
r42997 | |||
|
r43603 | impl<T> Drop for PyLeaked<T> { | ||
|
r43447 | fn drop(&mut self) { | ||
// py_shared_state should be alive since we do have | ||||
// a Python reference to the owner object. Taking GIL makes | ||||
// sure that the state is only accessed by this thread. | ||||
let gil = Python::acquire_gil(); | ||||
let py = gil.python(); | ||||
|
r43579 | if self.data.is_none() { | ||
|
r43603 | return; // moved to another PyLeaked | ||
|
r43579 | } | ||
|
r43582 | self.py_shared_state.decrease_leak_count(py, false); | ||
|
r43447 | } | ||
|
r42997 | } | ||
/// Defines a `py_class!` that acts as a Python iterator over a Rust iterator. | ||||
|
r43158 | /// | ||
/// TODO: this is a bit awkward to use, and a better (more complicated) | ||||
/// procedural macro would simplify the interface a lot. | ||||
/// | ||||
/// # Parameters | ||||
/// | ||||
/// * `$name` is the identifier to give to the resulting Rust struct. | ||||
/// * `$leaked` corresponds to `$leaked` in the matching `py_shared_ref!` call. | ||||
/// * `$iterator_type` is the type of the Rust iterator. | ||||
/// * `$success_func` is a function for processing the Rust `(key, value)` | ||||
/// tuple on iteration success, turning it into something Python understands. | ||||
/// * `$success_func` is the return type of `$success_func` | ||||
/// | ||||
/// # Example | ||||
/// | ||||
/// ``` | ||||
/// struct MyStruct { | ||||
/// inner: HashMap<Vec<u8>, Vec<u8>>; | ||||
/// } | ||||
/// | ||||
/// py_class!(pub class MyType |py| { | ||||
/// data inner: PySharedRefCell<MyStruct>; | ||||
/// | ||||
/// def __iter__(&self) -> PyResult<MyTypeItemsIterator> { | ||||
|
r43579 | /// let leaked_ref = self.inner_shared(py).leak_immutable()?; | ||
|
r43161 | /// MyTypeItemsIterator::from_inner( | ||
|
r43158 | /// py, | ||
|
r43579 | /// unsafe { leaked_ref.map(py, |o| o.iter()) }, | ||
|
r43158 | /// ) | ||
/// } | ||||
/// }); | ||||
/// | ||||
/// impl MyType { | ||||
/// fn translate_key_value( | ||||
/// py: Python, | ||||
/// res: (&Vec<u8>, &Vec<u8>), | ||||
/// ) -> PyResult<Option<(PyBytes, PyBytes)>> { | ||||
/// let (f, entry) = res; | ||||
/// Ok(Some(( | ||||
/// PyBytes::new(py, f), | ||||
/// PyBytes::new(py, entry), | ||||
/// ))) | ||||
/// } | ||||
/// } | ||||
/// | ||||
/// py_shared_ref!(MyType, MyStruct, inner, MyTypeLeakedRef); | ||||
/// | ||||
|
r43159 | /// py_shared_iterator!( | ||
|
r43158 | /// MyTypeItemsIterator, | ||
|
r43603 | /// PyLeaked<HashMap<'static, Vec<u8>, Vec<u8>>>, | ||
|
r43158 | /// MyType::translate_key_value, | ||
/// Option<(PyBytes, PyBytes)> | ||||
/// ); | ||||
/// ``` | ||||
|
r43159 | macro_rules! py_shared_iterator { | ||
|
r42997 | ( | ||
$name: ident, | ||||
|
r43447 | $leaked: ty, | ||
|
r42997 | $success_func: expr, | ||
$success_type: ty | ||||
) => { | ||||
py_class!(pub class $name |py| { | ||||
data inner: RefCell<Option<$leaked>>; | ||||
def __next__(&self) -> PyResult<$success_type> { | ||||
let mut inner_opt = self.inner(py).borrow_mut(); | ||||
|
r43579 | if let Some(leaked) = inner_opt.as_mut() { | ||
match leaked.get_mut(py).next() { | ||||
|
r42997 | None => { | ||
// replace Some(inner) by None, drop $leaked | ||||
inner_opt.take(); | ||||
Ok(None) | ||||
} | ||||
Some(res) => { | ||||
$success_func(py, res) | ||||
} | ||||
} | ||||
} else { | ||||
Ok(None) | ||||
} | ||||
} | ||||
def __iter__(&self) -> PyResult<Self> { | ||||
Ok(self.clone_ref(py)) | ||||
} | ||||
}); | ||||
impl $name { | ||||
pub fn from_inner( | ||||
py: Python, | ||||
|
r43160 | leaked: $leaked, | ||
|
r42997 | ) -> PyResult<Self> { | ||
Self::create_instance( | ||||
py, | ||||
|
r43160 | RefCell::new(Some(leaked)), | ||
|
r42997 | ) | ||
} | ||||
} | ||||
}; | ||||
} | ||||
|
r43583 | |||
#[cfg(test)] | ||||
#[cfg(any(feature = "python27-bin", feature = "python3-bin"))] | ||||
mod test { | ||||
use super::*; | ||||
use cpython::{GILGuard, Python}; | ||||
py_class!(class Owner |py| { | ||||
data string: PySharedRefCell<String>; | ||||
}); | ||||
py_shared_ref!(Owner, String, string, string_shared); | ||||
fn prepare_env() -> (GILGuard, Owner) { | ||||
let gil = Python::acquire_gil(); | ||||
let py = gil.python(); | ||||
let owner = | ||||
Owner::create_instance(py, PySharedRefCell::new("new".to_owned())) | ||||
.unwrap(); | ||||
(gil, owner) | ||||
} | ||||
#[test] | ||||
fn test_borrow_mut_while_leaked() { | ||||
let (gil, owner) = prepare_env(); | ||||
let py = gil.python(); | ||||
assert!(owner.string_shared(py).borrow_mut().is_ok()); | ||||
let _leaked = owner.string_shared(py).leak_immutable().unwrap(); | ||||
// TODO: will be allowed | ||||
assert!(owner.string_shared(py).borrow_mut().is_err()); | ||||
} | ||||
} | ||||