Struct qcell::QCellOwner
source · pub struct QCellOwner { /* private fields */ }alloc only.Expand description
Borrowing-owner of zero or more QCell instances.
The owner will have a temporally unique ID associated with it to
detect use of the wrong owner to access a cell at runtime, which
is a programming error. Temporally unique means that at any one
time, only one owner will hold that ID. This type derives the
owner ID from the address of an internal memory allocation which
this owner holds until it is dropped, which ensures that the ID is
temporally unique. The allocation is aligned to ensure that its
ID cannot collide with those created using QCellOwnerSeq.
In a no_std environment this requires the alloc feature
because it allocates memory. For a no_std environment without
alloc, consider using QCellOwnerSeq or QCellOwnerPinned.
Safety
This should successfully defend against all malicious and unsafe use. If not, please raise an issue. The same unique ID may later be allocated to someone else once you drop the returned owner, but this cannot be abused to cause unsafe access to cells because there will still be only one owner active at any one time with that ID. Also it cannot be used maliciously to access cells which don’t belong to the new caller, because you also need a reference to the cells. So for example if you have a graph of cells that is only accessible through a private structure, then if someone else gets the same owner ID later, it makes no difference, because they have no way to get a reference to those cells. In any case, you are probably going to drop all those cells at the same time as dropping the owner, because they are no longer of any use without the owner ID.
See crate documentation.
Implementations§
source§impl QCellOwner
impl QCellOwner
sourcepub fn id(&self) -> QCellOwnerID
pub fn id(&self) -> QCellOwnerID
Get the internal owner ID. This may be used to create QCell
instances without needing a borrow on this structure, which is
useful if this structure is already borrowed.
sourcepub fn cell<T>(&self, value: T) -> QCell<T>
pub fn cell<T>(&self, value: T) -> QCell<T>
Create a new cell owned by this owner instance. See also
QCell::new.
sourcepub fn ro<'a, T: ?Sized>(&'a self, qc: &'a QCell<T>) -> &'a T
pub fn ro<'a, T: ?Sized>(&'a self, qc: &'a QCell<T>) -> &'a T
Borrow contents of a QCell immutably (read-only). Many
QCell instances can be borrowed immutably at the same time
from the same owner. Panics if the QCell is not owned by
this QCellOwner.
sourcepub fn rw<'a, T: ?Sized>(&'a mut self, qc: &'a QCell<T>) -> &'a mut T
pub fn rw<'a, T: ?Sized>(&'a mut self, qc: &'a QCell<T>) -> &'a mut T
Borrow contents of a QCell mutably (read-write). Only one
QCell at a time can be borrowed from the owner using this
call. The returned reference must go out of scope before
another can be borrowed. Panics if the QCell is not owned
by this QCellOwner.
sourcepub fn rw2<'a, T: ?Sized, U: ?Sized>(
&'a mut self,
qc1: &'a QCell<T>,
qc2: &'a QCell<U>
) -> (&'a mut T, &'a mut U)
pub fn rw2<'a, T: ?Sized, U: ?Sized>( &'a mut self, qc1: &'a QCell<T>, qc2: &'a QCell<U> ) -> (&'a mut T, &'a mut U)
Borrow contents of two QCell instances mutably. Panics if
the two QCell instances point to the same memory. Panics
if either QCell is not owned by this QCellOwner.
sourcepub fn rw3<'a, T: ?Sized, U: ?Sized, V: ?Sized>(
&'a mut self,
qc1: &'a QCell<T>,
qc2: &'a QCell<U>,
qc3: &'a QCell<V>
) -> (&'a mut T, &'a mut U, &'a mut V)
pub fn rw3<'a, T: ?Sized, U: ?Sized, V: ?Sized>( &'a mut self, qc1: &'a QCell<T>, qc2: &'a QCell<U>, qc3: &'a QCell<V> ) -> (&'a mut T, &'a mut U, &'a mut V)
Borrow contents of three QCell instances mutably. Panics
if any pair of QCell instances point to the same memory.
Panics if any QCell is not owned by this QCellOwner.