rkyv 0.8.16

Zero-copy deserialization framework for Rust
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

use crate::ser::allocator::Arena;

#[cfg(feature = "std")]
mod detail {
    use core::cell::Cell;

    use crate::ser::allocator::Arena;

    thread_local! {
        static THREAD_ARENA: Cell<Option<Arena>> = const { Cell::new(None) };
    }

    pub fn with_arena<T>(f: impl FnOnce(&mut Arena) -> T) -> T {
        THREAD_ARENA.with(|thread_arena| {
            let mut arena = thread_arena.take().unwrap_or_default();

            let result = f(&mut arena);
            let capacity = arena.shrink();

            if let Some(other) = thread_arena.take() {
                if other.capacity() > capacity {
                    arena = other;
                }
            }
            thread_arena.set(Some(arena));

            result
        })
    }

    #[inline]
    pub fn clear_arena() {
        THREAD_ARENA.take();
    }
}

#[cfg(all(not(feature = "std"), target_has_atomic = "ptr",))]
mod detail {
    use core::{
        ptr::{self, NonNull},
        sync::atomic::{AtomicPtr, Ordering},
    };

    use crate::ser::allocator::Arena;

    static GLOBAL_ARENA: AtomicPtr<()> = AtomicPtr::new(ptr::null_mut());

    pub fn with_arena<T>(f: impl FnOnce(&mut Arena) -> T) -> T {
        let ptr = GLOBAL_ARENA.swap(ptr::null_mut(), Ordering::AcqRel);

        let mut arena = if let Some(raw) = NonNull::new(ptr) {
            unsafe { Arena::from_raw(raw) }
        } else {
            Arena::new()
        };

        let result = f(&mut arena);
        arena.shrink();

        let raw = arena.into_raw();

        let swap = GLOBAL_ARENA.compare_exchange(
            ptr::null_mut(),
            raw.as_ptr(),
            Ordering::AcqRel,
            Ordering::Relaxed,
        );
        if swap.is_err() {
            // Another arena was swapped in while we were executing `f`. We need
            // to free the current arena.
            unsafe {
                drop(Arena::from_raw(raw));
            }
        }

        result
    }

    #[inline]
    pub fn clear_arena() {
        let ptr = GLOBAL_ARENA.swap(ptr::null_mut(), Ordering::AcqRel);

        if let Some(raw) = NonNull::new(ptr) {
            unsafe {
                drop(Arena::from_raw(raw));
            }
        }
    }
}

#[cfg(all(not(feature = "std"), not(target_has_atomic = "ptr"),))]
mod detail {
    use crate::ser::allocator::Arena;

    pub fn with_arena<T>(f: impl FnOnce(&mut Arena) -> T) -> T {
        let mut arena = Arena::new();
        f(&mut arena)
    }

    #[inline]
    pub fn clear_arena() {}
}

/// Calls the given function with the builtin arena allocator.
///
/// When the `std` feature is enabled, the builtin arena allocator is a
/// thread-local variable, with one allocator per thread. When atomic pointers
/// are supported, it is a global static and all threads share the same arena.
/// Otherwise, this will create and drop a new arena each time it is called.
pub fn with_arena<T>(f: impl FnOnce(&mut Arena) -> T) -> T {
    detail::with_arena(f)
}

/// Clears the builtin arena allocator.
///
/// When the `std` feature is enabled, this only clears the allocator for the
/// current thread. When atomic pointers are supported, this will clear the
/// allocator for all threads. Otherwise, this function does nothing.
#[inline]
pub fn clear_arena() {
    detail::clear_arena()
}