box_swap 1.1.1

An atomic verison of Option<Box<T>>.
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

#![doc = include_str!("../README.md")]
#![no_std]

extern crate alloc;

use alloc::boxed::Box;
use core::{
    marker::PhantomData,
    sync::atomic::{AtomicPtr, Ordering},
};

/// An atomic version of [`Option<Box<T>>`]
pub struct BoxSwap<T> {
    ptr: AtomicPtr<T>,
    _data: PhantomData<Box<T>>,
}

unsafe impl<T> Send for BoxSwap<T> where Box<T>: Send {}
unsafe impl<T> Sync for BoxSwap<T> where Box<T>: Send {}

impl<T> BoxSwap<T> {
    /// Constructs a [`BoxSwap`] containing [`None`]
    pub const fn empty() -> Self {
        Self {
            ptr: AtomicPtr::new(core::ptr::null_mut()),
            _data: PhantomData,
        }
    }

    /// Constructs a [`BoxSwap`] containing [`Some(value)`](Some)
    pub fn with_value(value: Box<T>) -> Self {
        Self {
            ptr: AtomicPtr::new(Box::into_raw(value)),
            _data: PhantomData,
        }
    }

    /// Atomically stores `value`, returning the previous value
    pub fn swap(&self, value: Option<Box<T>>) -> Option<Box<T>> {
        let new = value.map(Box::into_raw).unwrap_or_else(core::ptr::null_mut);

        let old = self.ptr.swap(new, Ordering::AcqRel);
        if old.is_null() {
            None
        } else {
            Some(unsafe { Box::from_raw(old) })
        }
    }

    /// Atomically stores [`Some(value)`](Some), dropping the previous value
    pub fn store(&self, value: Box<T>) {
        drop(self.swap(Some(value)));
    }

    /// Atomically takes the value, leaving [`None`] in its place
    pub fn take(&self) -> Option<Box<T>> {
        self.swap(None)
    }

    /// Consumes the [`BoxSwap`], returning the wrapped value
    pub fn into_inner(mut self) -> Option<Box<T>> {
        self.take_mut()
    }

    /// Gets a mutable reference to the value
    pub fn get_mut(&mut self) -> Option<&mut T> {
        let ptr = *self.ptr.get_mut();
        if ptr.is_null() {
            None
        } else {
            Some(unsafe { &mut *ptr })
        }
    }

    /// [`BoxSwap::swap`] but without any atomic operations
    pub fn swap_mut(&mut self, value: Option<Box<T>>) -> Option<Box<T>> {
        let new = value.map(Box::into_raw).unwrap_or_else(core::ptr::null_mut);

        let old = core::mem::replace(self.ptr.get_mut(), new);
        if old.is_null() {
            None
        } else {
            Some(unsafe { Box::from_raw(old) })
        }
    }

    /// [`BoxSwap::store`] but without any atomic operations
    pub fn store_mut(&mut self, value: Box<T>) {
        drop(self.swap_mut(Some(value)));
    }

    /// [`BoxSwap::take`] but without any atomic operations
    pub fn take_mut(&mut self) -> Option<Box<T>> {
        self.swap_mut(None)
    }
}

impl<T> Drop for BoxSwap<T> {
    fn drop(&mut self) {
        drop(self.take_mut());
    }
}

impl<T> Default for BoxSwap<T> {
    fn default() -> Self {
        Self::empty()
    }
}

impl<T> From<Box<T>> for BoxSwap<T> {
    fn from(value: Box<T>) -> Self {
        Self::with_value(value)
    }
}

impl<T> From<Option<Box<T>>> for BoxSwap<T> {
    fn from(value: Option<Box<T>>) -> Self {
        value.map(Self::with_value).unwrap_or_else(Self::empty)
    }
}