Trait arc_swap::RefCnt [−][src]
pub unsafe trait RefCnt: Clone { type Base; fn into_ptr(me: Self) -> *mut Self::Base; fn as_ptr(me: &Self) -> *mut Self::Base; unsafe fn from_ptr(ptr: *const Self::Base) -> Self; fn can_null() -> bool; fn inc(me: &Self) { ... } unsafe fn dec(ptr: *const Self::Base) { ... } }
A trait describing smart reference counted pointers.
Note that in a form Option<Arc<T>>
is also a smart reference counted pointer, just one that
can hold NULL.
The trait is unsafe, because a wrong implementation will break the
ArcSwapAny
implementation and lead to UB.
This is not actually expected for downstream crate to implement, this is just means to reuse
code for Arc
and Option<Arc>
variants. However, it is theoretically possible (if you have
your own Arc
implementation).
Implementing it for Rc
is possible, but not useful (because the ArcSwap
then would not be
Send
nor Sync
, so there's very little advantage of using it if it can't be shared between
threads).
Aside from the obvious properties (like that incrementing and decrementing a reference count
cancel each out and that having less references tracked than how many things actually point to
the value is fine as long as the count doesn't drop to 0), it also must satisfy that if two
pointers have the same value, they point to the same object. This is specifically not true for
ZSTs, but it is true for Arc
s of ZSTs, because they have the reference counts just after the
value. It would be fine to point to a type-erased version of the same object, though (if one
could use this trait with unsized types in the first place).
Associated Types
type Base
The base type the pointer points to.
Required Methods
fn into_ptr(me: Self) -> *mut Self::Base
Converts the smart pointer into a raw pointer, without affecting the reference count.
This can be seen as kind of freezing the pointer ‒ it'll be later converted back using
from_ptr
.
The pointer must point to the value stored (and the value must be the same as one returned
by as_ptr
.
fn as_ptr(me: &Self) -> *mut Self::Base
Provides a view into the smart pointer as a raw pointer.
This must not affect the reference count ‒ the pointer is only borrowed.
unsafe fn from_ptr(ptr: *const Self::Base) -> Self
Converts a raw pointer back into the smart pointer, without affecting the reference count.
This is only called on values previously returned by into_ptr
.
However, it is not guaranteed to be 1:1 relation ‒ from_ptr
may be called more times than
into_ptr
temporarily provided the reference count never drops under 1 during that time
(the implementation sometimes owes a reference).
fn can_null() -> bool
Describes if the raw pointer can ever be null.
Things like Arc
are never null and can safely return false here. This is used only for
better formatting ‒ lying here won't cause an UB, but can cause uglier debug output or
panic inside debug formatting.
Provided Methods
fn inc(me: &Self)
Increments the reference count by one.
unsafe fn dec(ptr: *const Self::Base)
Decrements the reference count by one.
Note this is called on a raw pointer (one previously returned by
into_ptr
. This may lead to dropping of the reference count to 0 and
destruction of the internal pointer.
Implementations on Foreign Types
impl<T> RefCnt for Arc<T>
[src]
impl<T> RefCnt for Arc<T>
impl<T: NonNull> RefCnt for Option<T>
[src]
impl<T: NonNull> RefCnt for Option<T>