ext_php_rs/
boxed.rs

1//! A pointer type for heap allocation using the Zend memory manager.
2//!
3//! Heap memory in PHP is usually request-bound and allocated inside [memory
4//! arenas], which are cleared at the start and end of a PHP request. Allocating
5//! and freeing memory that is allocated on the Zend heap is done through two
6//! separate functions [`efree`] and [`emalloc`].
7//!
8//! As such, most heap-allocated PHP types **cannot** be allocated on the stack,
9//! such as [`ZendStr`], which is a dynamically-sized type, and therefore must
10//! be allocated on the heap. A regular [`Box`] would not work in this case, as
11//! the memory needs to be freed from a separate function `zend_string_release`.
12//! The [`ZBox`] type provides a wrapper which calls the relevant release
13//! functions based on the type and what is inside the implementation of
14//! [`ZBoxable`].
15//!
16//! This type is not created directly, but rather through a function implemented
17//! on the downstream type. For example, [`ZendStr`] has a function `new` which
18//! returns a [`ZBox<ZendStr>`].
19//!
20//! [memory arenas]: https://en.wikipedia.org/wiki/Region-based_memory_management
21//! [`ZendStr`]: crate::types::ZendStr
22//! [`emalloc`]: super::alloc::efree
23
24use std::{
25    borrow::Borrow,
26    fmt::Debug,
27    mem::ManuallyDrop,
28    ops::{Deref, DerefMut},
29    ptr::NonNull,
30};
31
32use super::alloc::efree;
33
34/// A pointer type for heap allocation using the Zend memory manager.
35///
36/// See the [module level documentation](../index.html) for more.
37pub struct ZBox<T: ZBoxable>(NonNull<T>);
38
39impl<T: ZBoxable> ZBox<T> {
40    /// Creates a new box from a given pointer.
41    ///
42    /// # Parameters
43    ///
44    /// * `ptr` - A non-null, well-aligned pointer to a `T`.
45    ///
46    /// # Safety
47    ///
48    /// Caller must ensure that `ptr` is non-null, well-aligned and pointing to
49    /// a `T`.
50    pub unsafe fn from_raw(ptr: *mut T) -> Self {
51        Self(NonNull::new_unchecked(ptr))
52    }
53
54    /// Returns the pointer contained by the box, dropping the box in the
55    /// process. The data pointed to by the returned pointer is not
56    /// released.
57    ///
58    /// # Safety
59    ///
60    /// The caller is responsible for managing the memory pointed to by the
61    /// returned pointer, including freeing the memory.
62    pub fn into_raw(self) -> &'static mut T {
63        let mut this = ManuallyDrop::new(self);
64        // SAFETY: All constructors ensure the contained pointer is well-aligned and
65        // dereferenceable.
66        unsafe { this.0.as_mut() }
67    }
68}
69
70impl<T: ZBoxable> Drop for ZBox<T> {
71    #[inline]
72    fn drop(&mut self) {
73        self.deref_mut().free()
74    }
75}
76
77impl<T: ZBoxable> Deref for ZBox<T> {
78    type Target = T;
79
80    #[inline]
81    fn deref(&self) -> &Self::Target {
82        // SAFETY: All constructors ensure the contained pointer is well-aligned and
83        // dereferenceable.
84        unsafe { self.0.as_ref() }
85    }
86}
87
88impl<T: ZBoxable> DerefMut for ZBox<T> {
89    #[inline]
90    fn deref_mut(&mut self) -> &mut Self::Target {
91        // SAFETY: All constructors ensure the contained pointer is well-aligned and
92        // dereferenceable.
93        unsafe { self.0.as_mut() }
94    }
95}
96
97impl<T: ZBoxable + Debug> Debug for ZBox<T> {
98    #[inline]
99    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
100        (**self).fmt(f)
101    }
102}
103
104impl<T: ZBoxable> Borrow<T> for ZBox<T> {
105    #[inline]
106    fn borrow(&self) -> &T {
107        self
108    }
109}
110
111impl<T: ZBoxable> AsRef<T> for ZBox<T> {
112    #[inline]
113    fn as_ref(&self) -> &T {
114        self
115    }
116}
117
118/// Implemented on types that can be heap allocated using the Zend memory
119/// manager. These types are stored inside a [`ZBox`] when heap-allocated, and
120/// the [`free`] method is called when the box is dropped.
121///
122/// # Safety
123///
124/// The default implementation of the [`free`] function uses the [`efree`]
125/// function to free the memory without calling any destructors.
126///
127/// The implementor must ensure that any time a pointer to the implementor is
128/// passed into a [`ZBox`] that the memory pointed to was allocated by the Zend
129/// memory manager.
130///
131/// [`free`]: #method.free
132pub unsafe trait ZBoxable {
133    /// Frees the memory pointed to by `self`, calling any destructors required
134    /// in the process.
135    fn free(&mut self) {
136        unsafe { efree(self as *mut _ as *mut u8) };
137    }
138}
ext_php_rs/boxed.rs

ext_php_rs/
boxed.rs
