arcu 0.1.2

An Rcu implementation using an Arc to keep the read critical section short and handle cleanup
Documentation 
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

//! This module contains the [`RcuRef`] type which is a smart pointer to the content of an [`super::Rcu`]

use alloc::sync::Arc;
use core::{fmt::Debug, ops::Deref, ptr::NonNull};

/// A smard pointer for a reference to the content of an [`super::Rcu`]
pub struct RcuRef<T, M>
where
    T: ?Sized,
    M: ?Sized,
{
    // we keep the arc to ensure its still alive, but we only access its data through data
    #[allow(dead_code)]
    arc: Arc<T>,
    data: NonNull<M>,
}

impl<T: ?Sized, M: ?Sized + Debug> Debug for RcuRef<T, M> {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("RcuRef")
            .field("data", &self.deref())
            .finish()
    }
}

impl<T: ?Sized> RcuRef<T, T> {
    /// Create a new `RcuRef` from an `Arc`
    pub fn new(arc: Arc<T>) -> Self {
        Self {
            data: arc.as_ref().into(),
            arc,
        }
    }
}

// use associated functions rather than methods so that we don't overlap
// with functions of the Deref Target type
impl<T: ?Sized, M: ?Sized> RcuRef<T, M> {
    /// apply the mapping function to the reference in this RcuRef
    pub fn map<N: ?Sized, F: for<'a> FnOnce(&'a M) -> &'a N>(
        reference: Self,
        f: F,
    ) -> RcuRef<T, N> {
        RcuRef {
            arc: reference.arc,
            // Safety: See deref
            data: f(unsafe { reference.data.as_ref() }).into(),
        }
    }

    /// try to apply the faillable mapping function to the reference in this RcuRef
    pub fn try_map<N: ?Sized, F: for<'a> FnOnce(&'a M) -> Option<&'a N>>(
        reference: Self,
        f: F,
    ) -> Option<RcuRef<T, N>> {
        // Safety: See deref
        let val = f(unsafe { reference.data.as_ref() })?;
        Some(RcuRef {
            arc: Arc::clone(&reference.arc),
            data: val.into(),
        })
    }

    /// Check whether the two RcuRefs reference values in the same epoch
    pub fn same_epoch<M2>(this: &Self, other: &RcuRef<T, M2>) -> bool {
        Arc::ptr_eq(&this.arc, &other.arc)
    }

    /// Compares the RcuRefs references via [`core::ptr::eq`]
    pub fn ptr_eq(this: &Self, other: &Self) -> bool {
        core::ptr::eq(this.data.as_ptr(), other.data.as_ptr())
    }

    /// Compares the RcuRefs references via [`core::ptr::addr_eq`]
    pub fn ptr_addr_eq(this: &Self, other: &Self) -> bool {
        std::ptr::addr_eq(this.data.as_ptr(), other.data.as_ptr())
    }

    /// Clones the RcuRef
    ///
    /// Not implementing clone to not shadow the inner types clone impl
    #[allow(clippy::should_implement_trait)]
    pub fn clone(this: &Self) -> Self {
        Self {
            arc: Arc::clone(&this.arc),
            data: this.data,
        }
    }

    /// Get a reference to root of the RcuRef
    ///
    /// i.e. the value that was stored in the Rcu
    /// before applying any mappings
    pub fn get_root(this: &Self) -> &T {
        &this.arc
    }
}

impl<T: ?Sized, M: ?Sized> Deref for RcuRef<T, M> {
    type Target = M;

    fn deref(&self) -> &Self::Target {
        // Safety: The pointer points into the arc we are holding
        // while we are alive so is the target
        // as the content is in an Rcu no mutable access is given out
        unsafe { self.data.as_ref() }
    }
}