rune/runtime/
unit.rs

Help
1//! A single execution unit in the rune virtual machine.
2//!
3//! A unit consists of a sequence of instructions, and lookaside tables for
4//! metadata like function locations.
5
6#[cfg(feature = "byte-code")]
7mod byte_code;
8mod storage;
9
10use core::fmt;
11
12use ::rust_alloc::sync::Arc;
13
14use serde::de::DeserializeOwned;
15use serde::{Deserialize, Serialize};
16
17use crate as rune;
18use crate::alloc::prelude::*;
19use crate::alloc::{self, Box, String, Vec};
20use crate::hash;
21use crate::runtime::{Call, ConstValue, DebugInfo, Inst, InstAddress, Rtti, StaticString};
22use crate::Hash;
23
24pub use self::storage::{ArrayUnit, EncodeError, UnitEncoder, UnitStorage};
25pub(crate) use self::storage::{BadInstruction, BadJump};
26
27#[cfg(feature = "byte-code")]
28pub use self::byte_code::ByteCodeUnit;
29
30/// Default storage implementation to use.
31#[cfg(not(rune_byte_code))]
32pub type DefaultStorage = ArrayUnit;
33/// Default storage implementation to use.
34#[cfg(rune_byte_code)]
35pub type DefaultStorage = ByteCodeUnit;
36
37/// Instructions and debug info from a single compilation.
38///
39/// See [`rune::prepare`] for more.
40#[derive(Debug, TryClone, Default, Serialize, Deserialize)]
41#[serde(bound = "S: Serialize + DeserializeOwned")]
42#[try_clone(bound = {S: TryClone})]
43pub struct Unit<S = DefaultStorage> {
44    /// The information needed to execute the program.
45    #[serde(flatten)]
46    logic: Logic<S>,
47    /// Debug info if available for unit.
48    debug: Option<Box<DebugInfo>>,
49}
50
51assert_impl!(Unit<DefaultStorage>: Send + Sync);
52
53/// Instructions from a single source file.
54#[derive(Debug, TryClone, Default, Serialize, Deserialize)]
55#[serde(rename = "Unit")]
56#[try_clone(bound = {S: TryClone})]
57pub struct Logic<S = DefaultStorage> {
58    /// Storage for the unit.
59    storage: S,
60    /// Where functions are located in the collection of instructions.
61    functions: hash::Map<UnitFn>,
62    /// Static strings.
63    static_strings: Vec<Arc<StaticString>>,
64    /// A static byte string.
65    static_bytes: Vec<Vec<u8>>,
66    /// Slots used for object keys.
67    ///
68    /// This is used when an object is used in a pattern match, to avoid having
69    /// to send the collection of keys to the virtual machine.
70    ///
71    /// All keys are sorted with the default string sort.
72    static_object_keys: Vec<Box<[String]>>,
73    /// Drop sets.
74    drop_sets: Vec<Arc<[InstAddress]>>,
75    /// Runtime information for types.
76    rtti: hash::Map<Arc<Rtti>>,
77    /// Named constants
78    constants: hash::Map<ConstValue>,
79}
80
81impl<S> Unit<S> {
82    /// Constructs a new unit from a pair of data and debug info.
83    #[inline]
84    pub fn from_parts(data: Logic<S>, debug: Option<DebugInfo>) -> alloc::Result<Self> {
85        Ok(Self {
86            logic: data,
87            debug: debug.map(Box::try_new).transpose()?,
88        })
89    }
90
91    /// Construct a new unit with the given content.
92    #[allow(clippy::too_many_arguments)]
93    #[inline]
94    pub(crate) fn new(
95        storage: S,
96        functions: hash::Map<UnitFn>,
97        static_strings: Vec<Arc<StaticString>>,
98        static_bytes: Vec<Vec<u8>>,
99        static_object_keys: Vec<Box<[String]>>,
100        drop_sets: Vec<Arc<[InstAddress]>>,
101        rtti: hash::Map<Arc<Rtti>>,
102        debug: Option<Box<DebugInfo>>,
103        constants: hash::Map<ConstValue>,
104    ) -> Self {
105        Self {
106            logic: Logic {
107                storage,
108                functions,
109                static_strings,
110                static_bytes,
111                static_object_keys,
112                drop_sets,
113                rtti,
114                constants,
115            },
116            debug,
117        }
118    }
119
120    /// Access unit data.
121    #[inline]
122    pub fn logic(&self) -> &Logic<S> {
123        &self.logic
124    }
125
126    /// Access debug information for the given location if it is available.
127    #[inline]
128    pub fn debug_info(&self) -> Option<&DebugInfo> {
129        Some(&**self.debug.as_ref()?)
130    }
131
132    /// Get raw underlying instructions storage.
133    #[inline]
134    pub(crate) fn instructions(&self) -> &S {
135        &self.logic.storage
136    }
137
138    /// Iterate over all static strings in the unit.
139    #[cfg(feature = "cli")]
140    #[inline]
141    pub(crate) fn iter_static_strings(&self) -> impl Iterator<Item = &Arc<StaticString>> + '_ {
142        self.logic.static_strings.iter()
143    }
144
145    /// Iterate over all static bytes in the unit.
146    #[cfg(feature = "cli")]
147    #[inline]
148    pub(crate) fn iter_static_bytes(&self) -> impl Iterator<Item = &[u8]> + '_ {
149        self.logic.static_bytes.iter().map(|v| &**v)
150    }
151
152    /// Iterate over all available drop sets.
153    #[cfg(feature = "cli")]
154    #[inline]
155    pub(crate) fn iter_static_drop_sets(&self) -> impl Iterator<Item = &[InstAddress]> + '_ {
156        self.logic.drop_sets.iter().map(|v| &**v)
157    }
158
159    /// Iterate over all constants in the unit.
160    #[cfg(feature = "cli")]
161    #[inline]
162    pub(crate) fn iter_constants(&self) -> impl Iterator<Item = (&Hash, &ConstValue)> + '_ {
163        self.logic.constants.iter()
164    }
165
166    /// Iterate over all static object keys in the unit.
167    #[cfg(feature = "cli")]
168    #[inline]
169    pub(crate) fn iter_static_object_keys(&self) -> impl Iterator<Item = (usize, &[String])> + '_ {
170        use core::iter;
171
172        let mut it = self.logic.static_object_keys.iter().enumerate();
173
174        iter::from_fn(move || {
175            let (n, s) = it.next()?;
176            Some((n, &s[..]))
177        })
178    }
179
180    /// Iterate over dynamic functions.
181    #[cfg(feature = "cli")]
182    #[inline]
183    pub(crate) fn iter_functions(&self) -> impl Iterator<Item = (Hash, &UnitFn)> + '_ {
184        self.logic.functions.iter().map(|(h, f)| (*h, f))
185    }
186
187    /// Lookup the static string by slot, if it exists.
188    #[inline]
189    pub(crate) fn lookup_string(&self, slot: usize) -> Option<&Arc<StaticString>> {
190        self.logic.static_strings.get(slot)
191    }
192
193    /// Lookup the static byte string by slot, if it exists.
194    #[inline]
195    pub(crate) fn lookup_bytes(&self, slot: usize) -> Option<&[u8]> {
196        Some(self.logic.static_bytes.get(slot)?)
197    }
198
199    /// Lookup the static object keys by slot, if it exists.
200    #[inline]
201    pub(crate) fn lookup_object_keys(&self, slot: usize) -> Option<&[String]> {
202        Some(self.logic.static_object_keys.get(slot)?)
203    }
204
205    #[inline]
206    pub(crate) fn lookup_drop_set(&self, set: usize) -> Option<&[InstAddress]> {
207        Some(self.logic.drop_sets.get(set)?)
208    }
209
210    /// Lookup run-time information for the given type hash.
211    #[inline]
212    pub(crate) fn lookup_rtti(&self, hash: &Hash) -> Option<&Arc<Rtti>> {
213        self.logic.rtti.get(hash)
214    }
215
216    /// Lookup a function in the unit.
217    #[inline]
218    pub(crate) fn function(&self, hash: &Hash) -> Option<&UnitFn> {
219        self.logic.functions.get(hash)
220    }
221
222    /// Lookup a constant from the unit.
223    #[inline]
224    pub(crate) fn constant(&self, hash: &Hash) -> Option<&ConstValue> {
225        self.logic.constants.get(hash)
226    }
227}
228
229impl<S> Unit<S>
230where
231    S: UnitStorage,
232{
233    #[inline]
234    pub(crate) fn translate(&self, jump: usize) -> Result<usize, BadJump> {
235        self.logic.storage.translate(jump)
236    }
237
238    /// Get the instruction at the given instruction pointer.
239    #[inline]
240    pub(crate) fn instruction_at(
241        &self,
242        ip: usize,
243    ) -> Result<Option<(Inst, usize)>, BadInstruction> {
244        self.logic.storage.get(ip)
245    }
246
247    /// Iterate over all instructions in order.
248    #[cfg(feature = "emit")]
249    #[inline]
250    pub(crate) fn iter_instructions(&self) -> impl Iterator<Item = (usize, Inst)> + '_ {
251        self.logic.storage.iter()
252    }
253}
254
255/// The kind and necessary information on registered functions.
256#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
257#[non_exhaustive]
258pub(crate) enum UnitFn {
259    /// Instruction offset of a function inside of the unit.
260    Offset {
261        /// Offset of the registered function.
262        offset: usize,
263        /// The way the function is called.
264        call: Call,
265        /// The number of arguments the function takes.
266        args: usize,
267        /// If the offset is a closure, this indicates the number of captures in
268        /// the first argument.
269        captures: Option<usize>,
270    },
271    /// An empty constructor of the type identified by the given hash.
272    EmptyStruct {
273        /// The type hash of the empty.
274        hash: Hash,
275    },
276    /// A tuple constructor of the type identified by the given hash.
277    TupleStruct {
278        /// The type hash of the tuple.
279        hash: Hash,
280        /// The number of arguments the tuple takes.
281        args: usize,
282    },
283}
284
285impl TryClone for UnitFn {
286    #[inline]
287    fn try_clone(&self) -> alloc::Result<Self> {
288        Ok(*self)
289    }
290}
291
292impl fmt::Display for UnitFn {
293    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
294        match self {
295            Self::Offset {
296                offset,
297                call,
298                args,
299                captures,
300            } => {
301                write!(
302                    f,
303                    "offset offset={offset}, call={call}, args={args}, captures={captures:?}"
304                )?;
305            }
306            Self::EmptyStruct { hash } => {
307                write!(f, "unit hash={hash}")?;
308            }
309            Self::TupleStruct { hash, args } => {
310                write!(f, "tuple hash={hash}, args={args}")?;
311            }
312        }
313
314        Ok(())
315    }
316}
317
318#[cfg(test)]
319static_assertions::assert_impl_all!(Unit: Send, Sync);
rune/runtime/unit.rs

rune/runtime/
unit.rs
