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
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
//! Garbage collection arenas for native code.

use std::borrow::Cow;
use std::error;
use std::fmt;
use std::ops::{Deref, DerefMut};

use crate::core::{ClassRegistry, TryConvertMut};
use crate::error::{Error, RubyException};
use crate::extn::core::exception::Fatal;
use crate::sys;
use crate::Artichoke;

/// Failed to create a new GC arena savepoint.
///
/// This error is returned by [`ArenaIndex::new`].
#[derive(Default, Debug, Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)]
#[allow(clippy::module_name_repetitions)]
pub struct ArenaSavepointError {
    _private: (),
}

impl ArenaSavepointError {
    /// Constructs a new, default `ArenaSavepointError`.
    #[must_use]
    pub const fn new() -> Self {
        Self { _private: () }
    }
}

impl fmt::Display for ArenaSavepointError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str("Failed to create internal garbage collection savepoint")
    }
}

impl error::Error for ArenaSavepointError {}

impl RubyException for ArenaSavepointError {
    fn message(&self) -> Cow<'_, [u8]> {
        Cow::Borrowed(b"Failed to create internal garbage collection savepoint")
    }

    fn name(&self) -> Cow<'_, str> {
        "fatal".into()
    }

    fn vm_backtrace(&self, interp: &mut Artichoke) -> Option<Vec<Vec<u8>>> {
        let _ = interp;
        None
    }

    fn as_mrb_value(&self, interp: &mut Artichoke) -> Option<sys::mrb_value> {
        let message = interp.try_convert_mut(self.message()).ok()?;
        let value = interp.new_instance::<Fatal>(&[message]).ok().flatten()?;
        Some(value.inner())
    }
}

impl From<ArenaSavepointError> for Error {
    fn from(exception: ArenaSavepointError) -> Self {
        Self::from(Box::<dyn RubyException>::from(exception))
    }
}

impl From<Box<ArenaSavepointError>> for Error {
    fn from(exception: Box<ArenaSavepointError>) -> Self {
        Self::from(Box::<dyn RubyException>::from(exception))
    }
}

impl From<ArenaSavepointError> for Box<dyn RubyException> {
    fn from(exception: ArenaSavepointError) -> Box<dyn RubyException> {
        Box::new(exception)
    }
}

impl From<Box<ArenaSavepointError>> for Box<dyn RubyException> {
    fn from(exception: Box<ArenaSavepointError>) -> Box<dyn RubyException> {
        exception
    }
}

/// Interpreter guard that acts as a GC arena savepoint.
///
/// Arena savepoints ensure mruby objects are reaped even when allocated with
/// the C API.
///
/// mruby manages objects created via the C API in a memory construct called
/// the [arena]. The arena is a stack and objects stored there are permanently
/// alive to avoid having to track lifetimes externally to the interperter.
///
/// An [`ArenaIndex`] is an index to some position of the stack. When restoring
/// an `ArenaIndex`, the stack pointer is moved. All objects beyond the pointer
/// are no longer live and are eligible to be collected at the next GC.
///
/// `ArenaIndex` implements [`Drop`], so letting it go out of scope is
/// sufficient to ensure objects get collected eventually.
///
/// [arena]: https://github.com/mruby/mruby/blob/master/doc/guides/gc-arena-howto.md
#[derive(Debug)]
#[allow(clippy::module_name_repetitions)]
pub struct ArenaIndex<'a> {
    index: i32,
    interp: &'a mut Artichoke,
}

impl<'a> ArenaIndex<'a> {
    /// Create a new arena savepoint.
    pub fn new(interp: &'a mut Artichoke) -> Result<Self, ArenaSavepointError> {
        unsafe {
            interp
                .with_ffi_boundary(|mrb| sys::mrb_sys_gc_arena_save(mrb))
                .map(move |index| Self { index, interp })
                .map_err(|_| ArenaSavepointError::new())
        }
    }

    /// Restore the arena stack pointer to its prior index.
    pub fn restore(self) {
        drop(self);
    }

    /// Access the inner guarded interpreter.
    ///
    /// The interpreter is also accessible via [`Deref`], [`DerefMut`],
    /// [`AsRef`], and [`AsMut`].
    #[inline]
    pub fn interp(&mut self) -> &mut Artichoke {
        self.interp
    }
}

impl<'a> AsRef<Artichoke> for ArenaIndex<'a> {
    #[inline]
    fn as_ref(&self) -> &Artichoke {
        &*self.interp
    }
}

impl<'a> AsMut<Artichoke> for ArenaIndex<'a> {
    #[inline]
    fn as_mut(&mut self) -> &mut Artichoke {
        self.interp
    }
}

impl<'a> Deref for ArenaIndex<'a> {
    type Target = Artichoke;

    #[inline]
    fn deref(&self) -> &Self::Target {
        &*self.interp
    }
}

impl<'a> DerefMut for ArenaIndex<'a> {
    #[inline]
    fn deref_mut(&mut self) -> &mut Self::Target {
        self.interp
    }
}

impl<'a> Drop for ArenaIndex<'a> {
    fn drop(&mut self) {
        let idx = self.index;
        // We can't panic in a drop impl, so ignore errors when crossing the
        // FFI boundary.
        let _ignored = unsafe {
            self.interp
                .with_ffi_boundary(|mrb| sys::mrb_sys_gc_arena_restore(mrb, idx))
        };
    }
}