openthread/ot/
otbox.rs

1// Copyright 2021 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5use std::marker::PhantomData;
6use std::ops::{Deref, DerefMut};
7
8/// A box for owning pointers to opaque types vended from the OpenThread API.
9///
10/// May be abbreviated as an [`OtBox`](crate::OtBox) to avoid confusion with [`std::boxed::Box`].
11///
12/// Internally, an [`ot::Box`](crate::ot::Box) contains the raw pointer to the underlying
13/// OpenThread object. Externally, the box appears to contain an instance
14/// of a type implementing [`ot::Boxable`](crate::ot::Boxable). References to the
15/// [`ot::Boxable`](crate::ot::Boxable) type are created from the underlying pointer as needed.
16///
17/// When an [`ot::Box`](crate::ot::Box) goes out of scope, the underlying object is finalized
18/// according to the OpenThread API for that type, via
19/// [`ot::Boxable::finalize`](crate::ot::Boxable::finalize).
20///
21/// The underlying pointer may be taken from the box without finalization
22/// by calling [`ot::Box::take_ot_ptr`](crate::ot::Box::take_ot_ptr), which consumes the
23/// [`ot::Box`](crate::ot::Box) and returns the pointer.
24///
25/// ## Safety ##
26///
27/// In general, the safety of this entire approach is dependent on the
28/// following assumptions on the language itself:
29///
30/// 1. **Casting from pointers to references**: Transmuting a `*mut Self::OtType` to a `&Self` is
31///    not itself undefined behavior assuming the pointer pointed to a valid object.
32/// 2. **Casting from references to pointers**: Transmuting a `&Self` that was previously created
33///    by assumption 1 back into a `*mut Self::OtType` will *always* yield the original pointer
34///    value.
35/// 3. **Behavior of Static Dispatch**: Traits implemented on `Self` and called via static
36///    dispatch will have `&self` references that obey assumption #2.
37/// 4. **No Spooky Stuff**: No weird pointer/reference manipulation happens behind the scenes,
38///    like the spooky stuff C++ does.
39#[repr(transparent)]
40pub struct Box<T: Boxable>(*mut T::OtType, PhantomData<T>);
41
42// SAFETY: Boxed values are owned values, so box itself can be considered `Send`/`Sync`
43//         as long as the contained type is considered `Send`/`Sync`.
44unsafe impl<T: Boxable + Send> Send for Box<T> {}
45unsafe impl<T: Boxable + Sync> Sync for Box<T> {}
46
47impl<T: Boxable + crate::ot::InstanceInterface> crate::ot::InstanceInterface for Box<T> {}
48
49impl<T: Boxable + std::fmt::Debug> std::fmt::Debug for Box<T> {
50    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
51        f.debug_tuple("OtBox").field(self.as_ref()).finish()
52    }
53}
54
55impl<T: Boxable> Box<T> {
56    /// Takes ownership of an OpenThread object by wrapping it in an `OtBox` instance.
57    /// Unless subsequently removed by a call to [`take_ot_ptr()`], the pointed-to
58    /// object will be finalized when the box goes out of scope.
59    ///
60    /// ## Safety ##
61    ///
62    /// This method is unsafe because it is effectively a deferred call
63    /// to [`Boxable::ref_from_ot_ptr`], which is also unsafe. When calling,
64    /// care must be taken to ensure the following is true:
65    ///
66    /// 1. The given pointer points to a valid instance of `T::OtType`.
67    /// 2. The caller has logical ownership of the object being pointed to.
68    pub unsafe fn from_ot_ptr(ptr: *mut T::OtType) -> Option<Self> {
69        if ptr.is_null() {
70            None
71        } else {
72            Some(Box(ptr, Default::default()))
73        }
74    }
75
76    /// Releases ownership of the contained OpenThread object, returning it's pointer.
77    pub fn take_ot_ptr(self) -> *mut T::OtType {
78        let ret = self.0;
79        std::mem::forget(self);
80        ret
81    }
82}
83
84impl<T: Boxable> AsRef<T> for Box<T> {
85    fn as_ref(&self) -> &T {
86        // SAFETY: `ref_from_ot_ptr` has two safety requirements on the pointer.
87        //         The pointer ultimatly comes from `ot::Box::from_ot_ptr`, which
88        //         has a superset of those requirements. Thus, the requirements
89        //         for this call are met.
90        unsafe { T::ref_from_ot_ptr(self.0).unwrap() }
91    }
92}
93
94impl<T: Boxable> AsMut<T> for Box<T> {
95    fn as_mut(&mut self) -> &mut T {
96        // SAFETY: `mut_from_ot_ptr` has two safety requirements on the pointer.
97        //         The pointer ultimatly comes from `ot::Box::from_ot_ptr`, which
98        //         has a superset of those requirements. Thus, the requirements
99        //         for this call are met.
100        unsafe { T::mut_from_ot_ptr(self.0).unwrap() }
101    }
102}
103
104impl<T: Boxable> Drop for Box<T> {
105    fn drop(&mut self) {
106        // SAFETY: The single safety requirement on `Boxable::finalize` is that it only
107        //         be called from `Drop::drop`, which is this method.
108        unsafe { self.as_mut().finalize() }
109    }
110}
111
112impl<T: Boxable> Deref for Box<T> {
113    type Target = T;
114
115    fn deref(&self) -> &Self::Target {
116        self.as_ref()
117    }
118}
119
120impl<T: Boxable> DerefMut for Box<T> {
121    fn deref_mut(&mut self) -> &mut Self::Target {
122        self.as_mut()
123    }
124}
125
126/// Trait for OpenThread Rust types for which an owned opaque instance is kept in a [`ot::Box<>`].
127///
128/// ## Safety ##
129///
130/// The safety of implementing this trait is dependent on the following assumptions:
131///
132/// 1. The type `Self` is never instantiated or passed by value. It must only ever
133///    used by reference (`&Self` or `&mut Self`).
134/// 2. No member of `Self` is ever accessed directly or exposed publicly.
135///
136/// Because of the above restrictions, `Self` is usually a zero-sized type.
137pub unsafe trait Boxable: Sized {
138    /// The underlying implementation-opaque OpenThread type used by the standard C-API.
139    type OtType: Sized;
140
141    /// Finalizes or frees the underlying OpenThread object.
142    ///
143    /// This method should only be called by the `Drop::drop` method on [`ot::Box`](crate::ot::Box).
144    /// It should not be called directly. This is usually the only method that
145    /// needs to be implemented from this trait: the default implementations of
146    /// the other methods is sufficient.
147    ///
148    /// ## Safety ##
149    ///
150    /// This method is considered unsafe to call directly because it invalidates
151    /// the underlying OpenThread object. This method should only ever be called
152    /// from a single place: `Drop::drop()` on `ot::Box`.
153    unsafe fn finalize(&mut self);
154
155    /// Creates a reference to a safe wrapper object from an OpenThread pointer.
156    ///
157    /// ## Safety ##
158    ///
159    /// This method is unsafe because it allows you to cast an arbitrary
160    /// pointer to a reference. When calling, care must be taken to ensure
161    /// the following is true:
162    ///
163    /// 1. The given pointer points to a valid instance of `Self::OtType` for the
164    ///    given lifetime.
165    unsafe fn ref_from_ot_ptr<'a>(ptr: *mut Self::OtType) -> Option<&'a Self> {
166        if ptr.is_null() {
167            None
168        } else {
169            Some(&*(ptr as *const Self))
170        }
171    }
172
173    /// Creates a reference to a safe wrapper object from an OpenThread const pointer.
174    ///
175    /// ## Safety ##
176    ///
177    /// This method is unsafe because it allows you to cast an arbitrary
178    /// pointer to a reference. When calling, care must be taken to ensure
179    /// the following is true:
180    ///
181    /// 1. The given pointer points to a valid instance of `Self::OtType` for the
182    ///    given lifetime.
183    unsafe fn ref_from_ot_const_ptr<'a>(ptr: *const Self::OtType) -> Option<&'a Self> {
184        if ptr.is_null() {
185            None
186        } else {
187            Some(&*(ptr as *const Self))
188        }
189    }
190
191    /// Creates a mutable reference to a safe wrapper object from an OpenThread pointer.
192    ///
193    /// ## Safety ##
194    ///
195    /// This method is unsafe because it allows you to cast an arbitrary
196    /// pointer to a reference. When calling, care must be taken to ensure
197    /// the following is true:
198    ///
199    /// 1. The given pointer points to a valid instance of `Self::OtType`.
200    /// 2. The given pointer is not `NULL`.
201    unsafe fn mut_from_ot_ptr<'a>(ptr: *mut Self::OtType) -> Option<&'a mut Self> {
202        if ptr.is_null() {
203            None
204        } else {
205            Some(&mut *(ptr as *mut Self))
206        }
207    }
208
209    /// Returns the underlying OpenThread pointer for this object.
210    /// The default implementation simply casts the reference to a pointer.
211    fn as_ot_ptr(&self) -> *mut Self::OtType {
212        (self as *const Self) as *mut Self::OtType
213    }
214}
openthread/ot/otbox.rs

openthread/ot/
otbox.rs
