artichoke_backend/
interpreter.rs

1use std::borrow::Cow;
2use std::error;
3use std::ffi::c_void;
4use std::fmt;
5
6use spinoso_exception::Fatal;
7
8use crate::Artichoke;
9use crate::core::{ClassRegistry, Eval, TryConvertMut};
10use crate::error::{Error, RubyException};
11use crate::extn;
12use crate::ffi;
13use crate::gc::{MrbGarbageCollection, State as GcState};
14use crate::release_metadata::ReleaseMetadata;
15use crate::state::State;
16use crate::sys;
17
18/// Create and initialize an [`Artichoke`] interpreter.
19///
20/// This function creates a new [`State`], embeds it in the [`sys::mrb_state`],
21/// initializes an [in memory virtual file system], and loads the [`extn`]
22/// extensions to Ruby Core and Stdlib.
23///
24/// [in memory virtual file system]: crate::load_path
25pub fn interpreter() -> Result<Artichoke, Error> {
26    let release_meta = ReleaseMetadata::new();
27    interpreter_with_config(release_meta)
28}
29
30/// Create and initialize an [`Artichoke`] interpreter with build metadata.
31///
32/// This function takes a customizable configuration for embedding metadata
33/// about how Artichoke was built. Otherwise, it behaves identically to the
34/// [`interpreter`] function.
35pub fn interpreter_with_config(config: ReleaseMetadata<'_>) -> Result<Artichoke, Error> {
36    let state = State::new()?;
37    let state = Box::new(state);
38    let alloc_ud = Box::into_raw(state).cast::<c_void>();
39    let raw = unsafe { sys::mrb_open_allocf(Some(sys::mrb_default_allocf), alloc_ud) };
40
41    // All operations using the interpreter must occur behind a function
42    // boundary so we can catch all errors and ensure we call `interp.close()`.
43    //
44    // Allowing the `?` operator to be used in the containing
45    // `interpreter_with_config` function would result in a memory leak of the
46    // interpreter and its heap.
47    let mut interp = unsafe { ffi::from_user_data(raw).map_err(|_| InterpreterAllocError::new())? };
48
49    match init(&mut interp, config) {
50        Ok(()) => Ok(interp),
51        Err(err) => {
52            // Cleanup and deallocate on error.
53            interp.close();
54            Err(err)
55        }
56    }
57}
58
59fn init(interp: &mut Artichoke, config: ReleaseMetadata<'_>) -> Result<(), Error> {
60    if let Some(ref mut state) = interp.state {
61        let mrb = unsafe { interp.mrb.as_mut() };
62        state.try_init_parser(mrb);
63    }
64
65    // mruby garbage collection relies on a fully initialized Array, which we
66    // won't have until after `extn::core` is initialized. Disable GC before
67    // init and clean up afterward.
68    let prior_gc_state = interp.disable_gc()?;
69
70    // Initialize Artichoke Core and Standard Library runtime
71    extn::init(interp, config)?;
72
73    // Load mrbgems
74    let mut arena = interp.create_arena_savepoint()?;
75
76    unsafe {
77        arena.interp().with_ffi_boundary(|mrb| sys::mrb_init_mrbgems(mrb))?;
78    }
79    arena.restore();
80
81    // mruby lazily initializes some core objects like `top_self` and generates
82    // a lot of garbage on start-up. Eagerly initialize the interpreter to
83    // provide predictable initialization behavior.
84    interp.create_arena_savepoint()?.interp().eval(b"")?;
85
86    if let GcState::Enabled = prior_gc_state {
87        interp.enable_gc()?;
88        interp.full_gc()?;
89    }
90    Ok(())
91}
92
93#[derive(Default, Debug, Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)]
94pub struct InterpreterAllocError {
95    _private: (),
96}
97
98impl InterpreterAllocError {
99    /// Constructs a new, default `InterpreterAllocError`.
100    #[must_use]
101    pub const fn new() -> Self {
102        Self { _private: () }
103    }
104}
105
106impl fmt::Display for InterpreterAllocError {
107    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
108        f.write_str("Failed to allocate Artichoke interpreter")
109    }
110}
111
112impl error::Error for InterpreterAllocError {}
113
114impl RubyException for InterpreterAllocError {
115    fn message(&self) -> Cow<'_, [u8]> {
116        Cow::Borrowed(b"Failed to allocate Artichoke Ruby interpreter")
117    }
118
119    fn name(&self) -> Cow<'_, str> {
120        "fatal".into()
121    }
122
123    fn vm_backtrace(&self, interp: &mut Artichoke) -> Option<Vec<Vec<u8>>> {
124        let _ = interp;
125        None
126    }
127
128    fn as_mrb_value(&self, interp: &mut Artichoke) -> Option<sys::mrb_value> {
129        let message = interp.try_convert_mut(self.message()).ok()?;
130        let value = interp.new_instance::<Fatal>(&[message]).ok().flatten()?;
131        Some(value.inner())
132    }
133}
134
135impl From<InterpreterAllocError> for Error {
136    fn from(exception: InterpreterAllocError) -> Self {
137        let err: Box<dyn RubyException> = Box::new(exception);
138        Self::from(err)
139    }
140}
141
142#[cfg(test)]
143mod tests {
144    #[test]
145    fn open_close() {
146        let interp = super::interpreter().unwrap();
147        interp.close();
148    }
149}
artichoke_backend/interpreter.rs

artichoke_backend/
interpreter.rs
