anchor-experiment 0.0.0

Experiment with Anchor API.
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

use std::ffi::{CString, OsString};
use std::marker::PhantomData;
use std::ops::{Deref, DerefMut};
use std::path::PathBuf;
use std::rc::Rc;
use std::sync::Arc;

/// A pointer type which guarantees a stable address.
///
/// This type must guarantee:
/// - It owns the data which is the target of its Deref impl.
/// - The memory address of that data will never be moved between immutable
///   dereferences.
pub unsafe trait StableDeref: Deref { }

unsafe impl<T> StableDeref for Box<T> { }
unsafe impl<T> StableDeref for Vec<T> { }

unsafe impl<T> StableDeref for Rc<T> { }
unsafe impl<T> StableDeref for Arc<T> { }
unsafe impl StableDeref for String { }
unsafe impl StableDeref for PathBuf { }
unsafe impl StableDeref for OsString { }
unsafe impl StableDeref for CString { }

/// A pointer type which guarantees a stable address under mutable conditions.
///
/// This type must guarantee:
/// - It owns the data which is the target of its Deref impl.
/// - The memory address of that data will never be moved between immutable
///   dereferences.
pub unsafe trait StableDerefMut: DerefMut { }

unsafe impl<T> StableDerefMut for Box<T> { }
unsafe impl<T> StableDerefMut for Vec<T> { }

pub struct Pin<'a, T: ?Sized> {
    _marker: PhantomData<&'a mut &'a ()>,
    data: T,
}

/// Pin an object in place.
///
/// This is intended to be combined with an Anchor to keep data from moving out
/// of its location on the stack.
pub fn pin<'a, T>(data: T) -> Pin<'a, T> {
    Pin {
        _marker: PhantomData,
        data
    }
}

/// Anchor a pointer in place.
/// 
/// This type makes it unsafe to move out of or mutably access the pointer
/// that it is wrapped around. This way, the value the pointer refers to is
/// guaranteed never to move again.
///
/// This can be applied to any pointer type that implements `StableDeref`, but
/// it can also be applied to a reference using pinning.
pub struct Anchor<Ptr: ?Sized> {
    ptr: Ptr,
}

impl<Ptr: StableDeref> Anchor<Ptr> {
    /// Construct a new Anchor from any StableDeref pointer.
    pub fn new(ptr: Ptr) -> Anchor<Ptr> {
        Anchor { ptr }
    }

    /// Convert this anchor to an anchored reference.
    pub fn as_ref<'a>(&'a self) -> Anchor<&'a Ptr::Target> {
        Anchor {
            ptr: &*self.ptr
        }
    }
}

impl<Ptr: StableDerefMut> Anchor<Ptr> {
    /// Convert this anchor to an anchored mutable reference.
    pub fn as_mut<'a>(&'a mut self) -> Anchor<&'a mut Ptr::Target> {
        Anchor {
            ptr: &mut *self.ptr
        }
    }
}

impl<'a, T> Anchor<&'a mut T> {
    /// Construct an anchor from pinned data.
    ///
    /// ```
    /// Anchor::pinned(&mut pin(0));
    /// ```
    pub fn pinned(data: &'a mut Pin<'a, T>) -> Anchor<&'a mut T> {
        Anchor { 
            ptr: &mut data.data
        }
    }
}

impl<'a, T> Anchor<&'a T> {
    /// Construct an anchor from pinned data.
    ///
    /// ```
    /// Anchor::pinned(&pin(0));
    /// ```
    pub fn pinned(data: &'a Pin<'a, T>) -> Anchor<&'a T> {
        Anchor { 
            ptr: &data.data
        }
    }
}

impl<Ptr> Anchor<Ptr> {
    /// Access a mutable reference to the underlying pointer. This method is
    /// unsafe.
    ///
    /// You must guarantee that you never move out of the reference you get
    /// when you call this.
    pub unsafe fn get_mut(&mut self) -> &mut Ptr {
        &mut self.ptr
    }
}

impl<Ptr> Deref for Anchor<Ptr> {
    type Target = Ptr;
    fn deref(&self) -> &Ptr {
        &self.ptr
    }
}