xarray 0.1.1

A Rust version of the XArray with copy-on-write capabilities
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
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

// SPDX-License-Identifier: MPL-2.0

use core::{marker::PhantomData, ptr::NonNull};

/// This represents a dormant mutable reference that can be awakened when the original reference
/// and all its derived references are dead.
///
/// See also
/// <https://github.com/rust-lang/rust/blob/35dfc67d94c47a6c6ae28c46e7dc1c547f772485/library/alloc/src/collections/btree/borrow.rs#L14>.
pub(super) struct DormantMutRef<'a, T> {
    ptr: NonNull<T>,
    _marker: PhantomData<&'a mut T>,
}

// SAFETY: `DormantMutRef<'a, T>` represents a value of `&'a mut T`.
unsafe impl<'a, T> Send for DormantMutRef<'a, T> where &'a mut T: Send {}
unsafe impl<'a, T> Sync for DormantMutRef<'a, T> where &'a mut T: Sync {}

impl<'a, T> DormantMutRef<'a, T> {
    /// Creates a dormant mutable reference and returns both the original reference and the dormant
    /// reference, so that the original reference can continue to be used.
    pub fn new(val: &'a mut T) -> (&'a mut T, DormantMutRef<'a, T>) {
        let mut ptr = NonNull::from(val);
        // SAFETY: The original reference is still exclusive and can continue to be used.
        let new_val = unsafe { ptr.as_mut() };
        (
            new_val,
            DormantMutRef {
                ptr,
                _marker: PhantomData,
            },
        )
    }

    /// Awakens the dormant references after the original reference and all its derived references
    /// are dead.
    ///
    /// # Safety
    ///
    /// The caller must ensure that the original reference and all its derived references
    /// (including derived dormant references) are now dead.
    pub unsafe fn awaken(mut self) -> &'a mut T {
        // SAFETY: The safety requirements of the method ensure that the reference is valid and
        // exclusive.
        unsafe { self.ptr.as_mut() }
    }

    /// Reborrows the dormant references after the original reference and all derived references
    /// are dead.
    ///
    /// # Safety
    ///
    /// The caller must ensure that the original reference and all its derived references
    /// (including derived dormant references) are now dead.
    pub unsafe fn reborrow(&mut self) -> &'a mut T {
        // SAFETY: The safety requirements of the method ensure that the reference is valid and
        // exclusive.
        unsafe { self.ptr.as_mut() }
    }
}

/// A "destroyable" immutable reference.
///
/// The Rust memory model [assumes][1] that all references passed as function arguments (including
/// indirect ones, e.g., structure fields of function arguments) must _not_ be invalidated while
/// the function is running.
///
/// [1]: https://github.com/rust-lang/miri/issues/3186#issuecomment-1826253846
///
/// However, this assumption is not necessarily true in certain cases. For example, when using
/// [`DormantMutRef`], we may want to make sure that all derived references are indeed dead so that
/// the dormant reference can be awakened. To do this, it is necessary to wrap the references in
/// this destroyable type before passing it to a function, otherwise the references will be alive
/// until the function returns.
///
/// By using this type, a reference is converted to a raw pointer, so no assumptions like the ones
/// above are made. Meanwhile, the raw pointer can be safely converted back to the reference for
/// use, since the lifetime is still properly tracked in the type.
pub(super) struct DestroyableRef<'a, T> {
    ptr: NonNull<T>,
    _marker: PhantomData<&'a T>,
}

// SAFETY: `DestroyableRef<'a, T>` represents a value of `&'a T`.
unsafe impl<'a, T> Send for DestroyableRef<'a, T> where &'a T: Send {}
unsafe impl<'a, T> Sync for DestroyableRef<'a, T> where &'a T: Sync {}

impl<'a, T> DestroyableRef<'a, T> {
    /// Creates a destroyable reference from an immutable reference.
    pub fn new(val: &'a T) -> Self {
        DestroyableRef {
            ptr: NonNull::from(val),
            _marker: PhantomData,
        }
    }

    /// Borrows the immutable reference.
    pub fn borrow(&self) -> &'a T {
        // SAFETY: `self` was converted from a value of `&'a T`.
        unsafe { self.ptr.as_ref() }
    }
}

/// A "destroyable" mutable reference.
///
/// For the rationale, see [`DestroyableRef`].
pub(super) struct DestroyableMutRef<'a, T> {
    ptr: NonNull<T>,
    _marker: PhantomData<&'a mut T>,
}

// SAFETY: `DestroyableMutRef<'a, T>` represents a value of `&'a mut T`.
unsafe impl<'a, T> Send for DestroyableMutRef<'a, T> where &'a mut T: Send {}
unsafe impl<'a, T> Sync for DestroyableMutRef<'a, T> where &'a mut T: Sync {}

impl<'a, T> DestroyableMutRef<'a, T> {
    /// Creates a destroyable reference from an immutable reference.
    pub fn new(val: &'a mut T) -> Self {
        DestroyableMutRef {
            ptr: NonNull::from(val),
            _marker: PhantomData,
        }
    }

    /// Borrows the mutable reference as an immutable reference.
    pub fn borrow(&self) -> &T {
        // SAFETY: `self` was converted from a value of `&'a mut T`.
        unsafe { self.ptr.as_ref() }
    }

    /// Borrows the mutable reference.
    pub fn borrow_mut(&mut self) -> &mut T {
        // SAFETY: `self` was converted from a value of `&'a mut T`.
        unsafe { self.ptr.as_mut() }
    }

    /// Moves the mutable reference out.
    pub fn into(mut self) -> &'a mut T {
        // SAFETY: `self` was converted from a value of `&'a mut T`.
        unsafe { self.ptr.as_mut() }
    }
}