luxolus/pyo3
2
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

Merge pull request #1748 from PyO3/more_doc

Browse source 
some more docstring proofreading
This commit is contained in:
David Hewitt 2021-08-01 09:40:51 +01:00 committed by GitHub
parent fab135c1df 9c33c988ed
commit 9a69d120b4
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 42 additions and 40 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

30
src/gil.rs
View file

@ -1,6 +1,6 @@
// Copyright (c) 2017-present PyO3 Project and Contributors
//! Interaction with python's global interpreter lock
//! Interaction with Python's global interpreter lock
use crate::{ffi, internal_tricks::Unsendable, Python};
use parking_lot::{const_mutex, Mutex, Once};
@ -14,21 +14,21 @@ use std::{
static START: Once = Once::new();
thread_local! {
/// This is a internal counter in pyo3 monitoring whether this thread has the GIL.
/// This is an internal counter in pyo3 monitoring whether this thread has the GIL.
///
/// It will be incremented whenever a GILGuard or GILPool is created, and decremented whenever
/// they are dropped.
///
/// As a result, if this thread has the GIL, GIL_COUNT is greater than zero.
///
/// pub(crate) because it is manipulated temporarily by Python::allow_threads
/// pub(crate) because it is manipulated temporarily by `Python::allow_threads`.
pub(crate) static GIL_COUNT: Cell<usize> = Cell::new(0);
/// Temporally hold objects that will be released when the GILPool drops.
/// Temporarily hold objects that will be released when the GILPool drops.
static OWNED_OBJECTS: RefCell<Vec<NonNull<ffi::PyObject>>> = RefCell::new(Vec::with_capacity(256));
}
/// Check whether the GIL is acquired.
/// Checks whether the GIL is acquired.
///
/// Note: This uses pyo3's internal count rather than PyGILState_Check for two reasons:
/// 1) for performance
@ -174,7 +174,7 @@ where
/// RAII type that represents the Global Interpreter Lock acquisition.
///
/// Users are strongly encouraged to [`Python::with_gil`](struct.Python.html#method.with_gil)
/// Users are strongly encouraged to use [`Python::with_gil`](struct.Python.html#method.with_gil)
/// instead of directly constructing this type.
/// See [`Python::acquire_gil`](struct.Python.html#method.acquire_gil) for more.
///
@ -355,7 +355,7 @@ pub struct GILPool {
}
impl GILPool {
/// Create a new `GILPool`. This function should only ever be called with the GIL.
/// Creates a new `GILPool`. This function should only ever be called with the GIL held.
///
/// It is recommended not to use this API directly, but instead to use `Python::new_pool`, as
/// that guarantees the GIL is held.
@ -402,8 +402,8 @@ impl Drop for GILPool {
}
}
/// Register a Python object pointer inside the release pool, to have reference count increased
/// next time the GIL is acquired in pyo3.
/// Registers a Python object pointer inside the release pool, to have its reference count increased
/// the next time the GIL is acquired in pyo3.
///
/// If the GIL is held, the reference count will be increased immediately instead of being queued
/// for later.
@ -418,8 +418,8 @@ pub unsafe fn register_incref(obj: NonNull<ffi::PyObject>) {
}
}
/// Register a Python object pointer inside the release pool, to have reference count decreased
/// next time the GIL is acquired in pyo3.
/// Registers a Python object pointer inside the release pool, to have its reference count decreased
/// the next time the GIL is acquired in pyo3.
///
/// If the GIL is held, the reference count will be decreased immediately instead of being queued
/// for later.
@ -434,7 +434,7 @@ pub unsafe fn register_decref(obj: NonNull<ffi::PyObject>) {
}
}
/// Register an owned object inside the GILPool.
/// Registers an owned object inside the GILPool, to be released when the GILPool drops.
///
/// # Safety
/// The object must be an owned Python reference.
@ -444,14 +444,14 @@ pub unsafe fn register_owned(_py: Python, obj: NonNull<ffi::PyObject>) {
let _ = OWNED_OBJECTS.try_with(|holder| holder.borrow_mut().push(obj));
}
/// Increment pyo3's internal GIL count - to be called whenever GILPool or GILGuard is created.
/// Increments pyo3's internal GIL count - to be called whenever GILPool or GILGuard is created.
#[inline(always)]
fn increment_gil_count() {
// Ignores the error in case this function called from `atexit`.
let _ = GIL_COUNT.try_with(|c| c.set(c.get() + 1));
}
/// Decrement pyo3's internal GIL count - to be called whenever GILPool or GILGuard is dropped.
/// Decrements pyo3's internal GIL count - to be called whenever GILPool or GILGuard is dropped.
#[inline(always)]
fn decrement_gil_count() {
// Ignores the error in case this function called from `atexit`.
@ -465,7 +465,7 @@ fn decrement_gil_count() {
});
}
/// Ensure the GIL is held, used in the implementation of Python::with_gil
/// Ensures the GIL is held, used in the implementation of `Python::with_gil`.
pub(crate) fn ensure_gil() -> EnsureGIL {
if gil_is_acquired() {
EnsureGIL(None)

6
src/pyclass.rs
View file

@ -12,11 +12,11 @@ use std::{
ptr,
};
/// If `PyClass` is implemented for `T`, then we can use `T` in the Python world,
/// via `PyCell`.
/// If `PyClass` is implemented for a Rust type `T`, then we can use `T` in the Python
/// world, via `PyCell`.
///
/// The `#[pyclass]` attribute automatically implements this trait for your Rust struct,
/// so you don't have to use this trait directly.
/// so you normally don't have to use this trait directly.
pub trait PyClass:
PyTypeInfo<AsRefTarget = PyCell<Self>> + PyClassImpl<Layout = PyCell<Self>>
{

20
src/pyclass_init.rs
View file

@ -29,7 +29,7 @@ pub trait PyObjectInit<T>: Sized {
private_decl! {}
}
/// Initializer for Python native type, like `PyDict`.
/// Initializer for Python native types, like `PyDict`.
pub struct PyNativeTypeInitializer<T: PyTypeInfo>(PhantomData<T>);
impl<T: PyTypeInfo> PyObjectInit<T> for PyNativeTypeInitializer<T> {
@ -130,14 +130,14 @@ pub struct PyClassInitializer<T: PyClass> {
}
impl<T: PyClass> PyClassInitializer<T> {
/// Construct new initializer from value `T` and base class' initializer.
/// Constructs a new initializer from value `T` and base class' initializer.
///
/// We recommend to mainly use `add_subclass`, instead of directly call `new`.
/// It is recommended to use `add_subclass` instead of this method for most usage.
pub fn new(init: T, super_init: <T::BaseType as PyClassBaseType>::Initializer) -> Self {
Self { init, super_init }
}
/// Constructs a new initializer from base class' initializer.
/// Constructs a new initializer from an initializer for the base class.
///
/// # Examples
/// ```
@ -174,7 +174,7 @@ impl<T: PyClass> PyClassInitializer<T> {
PyClassInitializer::new(subclass_value, self)
}
/// Create a new PyCell and initialize it.
/// Creates a new PyCell and initializes it.
#[doc(hidden)]
pub fn create_cell(self, py: Python) -> PyResult<*mut PyCell<T>>
where
@ -183,8 +183,8 @@ impl<T: PyClass> PyClassInitializer<T> {
unsafe { self.create_cell_from_subtype(py, T::type_object_raw(py)) }
}
/// Create a new PyCell and initialize it given a typeobject `subtype`.
/// Called by our `tp_new` generated by the `#[new]` attribute.
/// Creates a new PyCell and initializes it given a typeobject `subtype`.
/// Called by the Python `tp_new` implementation generated by a `#[new]` function in a `#[pymethods]` block.
///
/// # Safety
/// `subtype` must be a valid pointer to the type object of T or a subclass.
@ -207,15 +207,15 @@ impl<T: PyClass> PyObjectInit<T> for PyClassInitializer<T> {
py: Python,
subtype: *mut PyTypeObject,
) -> PyResult<*mut ffi::PyObject> {
/// Layout of a PyCellBase after base new has been called, but borrow flag has not yet been
/// initialized.
/// Layout of a PyCellBase after base new has been called, but the borrow flag has not
/// yet been initialized.
#[repr(C)]
struct PartiallyInitializedPyCellBase<T> {
_ob_base: T,
borrow_flag: MaybeUninit<Cell<BorrowFlag>>,
}
/// Layout of a PyCell after base new has been called, but contents have not yet been
/// Layout of a PyCell after base new has been called, but the contents have not yet been
/// written.
#[repr(C)]
struct PartiallyInitializedPyCell<T: PyClass> {

8
src/pyclass_slots.rs
View file

@ -1,8 +1,8 @@
//! This module contains additional fields for `#[pyclass]`..
//! Mainly used by our proc-macro codes.
//! This module contains additional fields for `#[pyclass]`.
//! Mainly used by PyO3's proc-macro code.
use crate::{ffi, Python};
/// Represents `__dict__` field for `#[pyclass]`.
/// Represents the `__dict__` field for `#[pyclass]`.
pub trait PyClassDict {
/// Whether this `__dict__` field is capable of holding a dictionary.
const IS_DUMMY: bool = true;
@ -14,7 +14,7 @@ pub trait PyClassDict {
private_decl! {}
}
/// Represents `__weakref__` field for `#[pyclass]`.
/// Represents the `__weakref__` field for `#[pyclass]`.
pub trait PyClassWeakRef {
/// Whether this `weakref` type is capable of holding weak references.
const IS_DUMMY: bool = true;

18
src/type_object.rs
View file

@ -11,32 +11,34 @@ use crate::{ffi, AsPyPointer, PyErr, PyNativeType, PyObject, PyResult, Python};
use parking_lot::{const_mutex, Mutex};
use std::thread::{self, ThreadId};
/// `T: PyLayout<U>` represents that `T` is a concrete representaion of `U` in Python heap.
/// `T: PyLayout<U>` represents that `T` is a concrete representation of `U` in the Python heap.
/// E.g., `PyCell` is a concrete representaion of all `pyclass`es, and `ffi::PyObject`
/// is of `PyAny`.
///
/// This trait is intended to be used internally.
pub unsafe trait PyLayout<T> {}
/// `T: PySizedLayout<U>` represents `T` is not a instance of
/// `T: PySizedLayout<U>` represents that `T` is not a instance of
/// [`PyVarObject`](https://docs.python.org/3.8/c-api/structures.html?highlight=pyvarobject#c.PyVarObject).
/// , in addition that `T` is a concrete representaion of `U`.
/// In addition, that `T` is a concrete representaion of `U`.
pub trait PySizedLayout<T>: PyLayout<T> + Sized {}
/// Python type information.
/// All Python native types(e.g., `PyDict`) and `#[pyclass]` structs implement this trait.
/// All Python native types (e.g., `PyDict`) and `#[pyclass]` structs implement this trait.
///
/// This trait is marked unsafe because:
/// - specifying the incorrect layout can lead to memory errors
/// - the return value of type_object must always point to the same PyTypeObject instance
///
/// It is safely implemented by the `pyclass` macro.
pub unsafe trait PyTypeInfo: Sized {
/// Class name
/// Class name.
const NAME: &'static str;
/// Module name, if any
/// Module name, if any.
const MODULE: Option<&'static str>;
/// Utility type to make Py::as_ref work
/// Utility type to make Py::as_ref work.
type AsRefTarget: crate::PyNativeType;
/// PyTypeObject instance for this type.
@ -73,7 +75,7 @@ where
}
}
/// Lazy type object for PyClass
/// Lazy type object for PyClass.
#[doc(hidden)]
pub struct LazyStaticType {
// Boxed because Python expects the type object to have a stable address.