1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160

use super::{internal::*};
use alloc::boxed::Box;
use core::{hash::*, ptr};
use crossbeam_epoch::{Guard, pin};

/// `Xarc` is a derefenceable atomically refcounted smart pointer.
/// `Xarc` is roughly equivalent to `Arc` but is compatible with `AtomicXarc`.
/// 
/// # Examples
/// 
/// Here is some typical usage of `Xarc`.
/// ```
/// use xarc::Xarc;
/// 
/// let xarc = Xarc::new(42);
/// let same = xarc.clone();
/// let different = Xarc::new(42);
/// 
/// // Null checks
/// assert!(!xarc.is_null());
/// assert_ne!(xarc, Xarc::null());
/// 
/// // Pointer comparisons
/// assert_eq!(xarc, same);
/// assert_ne!(xarc, different);
/// 
/// // Value comparisons
/// assert_eq!(xarc.maybe_deref().unwrap(), different.maybe_deref().unwrap());
/// assert_eq!(Xarc::<i64>::null().maybe_deref(), None);
/// ```
/// 
/// When implementing a container you often need structures with an immutable part,
/// such as a pointer to another part of the structure, and a separate value that
/// you can `take` to return a value as you remove it. `UnsafeCell` comes to the rescue.
/// ```
/// use core::{cell::UnsafeCell, mem};
/// use xarc::Xarc;
/// 
/// struct Example {
///     immutable: i64,
///     takeable: UnsafeCell<i64>,
/// }
/// 
/// let mut xarc = Xarc::new(Example {immutable: 0, takeable: UnsafeCell::new(42)});
/// 
/// let value = unsafe {
///     // You had better know what you're doing at this point. 🙂
///     core::mem::take(&mut *xarc.maybe_deref().unwrap().takeable.get())
/// };
/// 
/// assert_eq!(value, 42);
/// ```

#[derive(Debug, Eq)]
pub struct Xarc<T: Send> {
    pub(crate) ptr: *mut XarcData<T>,
}

impl<T: Send> Xarc<T> {
    /// Initialize the smart pointer with `value`.
    #[must_use]
    pub fn new(value: T) -> Self {
        Xarc {
            ptr: Box::into_raw(Box::new(XarcData::new(value))),
        }
    }

    /// Initialize the smart pointer with null.
    #[must_use]
    pub fn null() -> Self {
        Xarc {
            ptr: ptr::null_mut(),
        }
    }

    #[must_use]
    pub(crate) fn init(ptr: *mut XarcData<T>) -> Self {
        Xarc {
            ptr,
        }
    }

    pub(crate) fn try_from(ptr: *mut XarcData<T>, guard: &Guard) -> Result<Self, ()> {
        try_increment(ptr, guard)?;
        Ok(Xarc::init(ptr))
    }

    /// Reset the smart pointer to null.
    pub fn reset(&mut self) {
        let guard = pin();
        decrement(self.ptr, &guard);
        self.ptr = ptr::null_mut();
    }

    /// Check if the smart pointer is null.
    #[must_use]
    pub fn is_null(&self) -> bool {
        self.ptr.is_null()
    }

    /// Dereference the pointer only if it is not null.
    /// None will be returned if it is null.
    #[must_use]
    pub fn maybe_deref(&self) -> Option<&T> {
        if !self.ptr.is_null() {
            unsafe {
                Some(&(*self.ptr).value)
            }
        }
        else {
            None
        }
    }

    /// Dereference the pointer only if it is not null.
    /// None will be returned if it is null.
    /// 
    /// # Safety
    /// - This should be called only if you're absolutely,
    /// 100% certain that nobody else could possibly have access to this data
    /// or if you *really* know what you're doing.
    #[must_use]
    pub unsafe fn unguarded_maybe_deref_mut(&mut self) -> Option<&mut T> {
        if !self.ptr.is_null() {
            Some(&mut (*self.ptr).value)
        }
        else {
            None
        }
    }
}

impl<T: Send> Clone for Xarc<T> {
    fn clone(&self) -> Self {
        unguarded_increment(self.ptr);
        Xarc::init(self.ptr)
    }
}

impl<T: Send> Drop for Xarc<T> {
    fn drop(&mut self) {
        decrement(self.ptr, &pin());
    }
}

impl<T: Send> Hash for Xarc<T> {
    fn hash<H: Hasher>(&self, state: &mut H) {
        ptr::hash(self.ptr, state);
    }
}

impl<T: Send> PartialEq for Xarc<T> {
    #[must_use]
    fn eq(&self, other: &Self) -> bool {
        self.ptr == other.ptr
    }
}

unsafe impl<T: Send> Send for Xarc<T> {}
unsafe impl<T: Send> Sync for Xarc<T> {}