framealloc 0.11.1

Intent-aware, thread-smart memory allocation for Rust game engines
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

//! Frame scope guards for RAII-style frame management.

#![allow(deprecated)]  // Internal uses of deprecated types are intentional

use crate::api::alloc::SmartAlloc;
use crate::core::tls;

/// A guard that represents a frame scope.
///
/// When dropped, the frame arena is reset to its state when the guard was created.
/// This is useful for sub-frame temporary allocations.
///
/// # Example
///
/// ```rust,no_run
/// use framealloc::SmartAlloc;
///
/// let alloc = SmartAlloc::with_defaults();
///
/// {
///     let _scope = alloc.frame_scope();
///     let temp = alloc.frame_alloc::<[u8; 1024]>();
///     // temp is valid here
/// } // temp is invalidated here
/// ```
#[deprecated(
    since = "0.11.1",
    note = "framealloc is deprecated. Use `memkit::MkScope` instead (available in memkit 0.12+)"
)]
pub struct FrameGuard<'a> {
    alloc: &'a SmartAlloc,
    saved_head: usize,
}

impl<'a> FrameGuard<'a> {
    /// Create a new frame guard.
    pub(crate) fn new(alloc: &'a SmartAlloc) -> Self {
        let saved_head = tls::with_tls(|tls| tls.frame_head());
        Self { alloc, saved_head }
    }

    /// Allocate from this scope's frame arena.
    pub fn alloc<T>(&self) -> *mut T {
        self.alloc.frame_alloc::<T>()
    }
}

impl<'a> Drop for FrameGuard<'a> {
    fn drop(&mut self) {
        tls::with_tls(|tls| {
            tls.reset_frame_to(self.saved_head);
        });
    }
}

/// A trait for types that can provide a frame scope.
#[deprecated(
    since = "0.11.1",
    note = "framealloc is deprecated. Use `memkit::MkScope` instead (available in memkit 0.12+)"
)]
pub trait FrameScope {
    /// Create a new frame scope.
    fn frame_scope(&self) -> FrameGuard<'_>;
}

impl FrameScope for SmartAlloc {
    fn frame_scope(&self) -> FrameGuard<'_> {
        FrameGuard::new(self)
    }
}