archery/shared_pointer/kind/
mod.rs

1use core::fmt::Debug;
2
3/// Trait for [type constructors](https://en.wikipedia.org/wiki/Type_constructor) of
4/// reference-counting pointers.
5///
6/// # Safety
7///
8/// `T` may be `!`[`Unpin`], and [`SharedPointer`][1] may be held in a pinned
9/// form ([`Pin`][2]`<SharedPointer<T, Self>>`).
10/// As such, the implementation of this trait must uphold the pinning invariants
11/// for `T` while it's held in `Self`. Specifically, this necessitates the
12/// following:
13///
14/// - `&mut T` is only exposed through the trait methods returning `&mut T`.
15///
16/// - The implementor must not move out the contained `T` unless the semantics
17///   of trait methods demands that.
18///
19/// - [`Self::drop`] drops `T` in place.
20///
21/// [1]: crate::shared_pointer::SharedPointer
22/// [2]: core::pin::Pin
23//
24// There are two conditions for types implementing this trait to be used in a safe way:
25//
26// 1. Always use the correct type `T`.
27// 2. Make sure that you use it wrapped in something that derives the correct auto-traits taking
28//    into account the type of `T`.
29//
30// To elaborate on point 2: a `ArcK` will always implement `Send + Sync`, but that
31// is only safe if the actually type that `ArcK` holds is in fact `Send + Sync`.
32// This means that a safe wrapper around this type must make sure it does not implement
33// `Send + Sync` unless `T: Send + Sync`.  This is holds true for `SharedPointer` since it has a
34// phantom field with `T`, thus the compiler will only make `SharedPointer<T>` implement
35// `Send + Sync` if `T: Send + Sync`.
36pub unsafe trait SharedPointerKind: Sized + Debug {
37    fn new<T>(v: T) -> Self;
38    fn from_box<T>(v: Box<T>) -> Self;
39    unsafe fn as_ptr<T>(&self) -> *const T;
40    unsafe fn deref<T>(&self) -> &T;
41    unsafe fn try_unwrap<T>(self) -> Result<T, Self>;
42    unsafe fn get_mut<T>(&mut self) -> Option<&mut T>;
43    unsafe fn make_mut<T: Clone>(&mut self) -> &mut T;
44    unsafe fn strong_count<T>(&self) -> usize;
45    #[must_use]
46    unsafe fn clone<T>(&self) -> Self;
47    unsafe fn drop<T>(&mut self);
48}
49
50mod arc;
51#[cfg(feature = "triomphe")]
52mod arct;
53mod rc;
54
55use alloc::boxed::Box;
56#[doc(inline)]
57pub use arc::ArcK;
58#[cfg(feature = "triomphe")]
59#[doc(inline)]
60pub use arct::ArcTK;
61#[doc(inline)]
62pub use rc::RcK;
archery/shared_pointer/kind/mod.rs

archery/shared_pointer/kind/
mod.rs
