Add function yielding and resuming

Sometimes, a builtin function may need to call out to another function
(user-defined or otherwise). Previously, we were just calling the
function and popping the stack frame, leaving no room for the new
function to be called. This introduces a `FunctionResult` and
`FunctionState` that get passed between these builtin functions. A
builtin function will receive a FunctionState that tells it whether it
is currently beginning or being resumed and can act accordingly. A
builtin function will in turn return a FunctionResult, which can either
be to return and push a value to the stack, return without pushing a
value (value is already on top of the stack), or yield execution back to
the VM (implying that a new stack frame has been pushed with a new
function to execute).

Having to call a new function and resume is a bit unwieldy and
un-ergonomic, and making a macro to help write these would be nice, but
it looks like a procedural macro may be required to really enable this.
For now, we will write these yields by hand and once it becomes truly
too much, we can start looking at writing a macro library to handle this
case.

Signed-off-by: Alek Ratzloff <alekratz@gmail.com>

src/obj/function.rs

@@ -6,18 +6,59 @@ use gc::{Finalize, Trace};
 
 use crate::obj::macros::*;
 use crate::obj::{make_ptr, BaseObjInst, Obj, ObjP};
-use crate::vm::{Argc, Chunk, Frame, Vm};
+use crate::vm::{Argc, Chunk, Frame, Function, Vm};
+
+////////////////////////////////////////////////////////////////////////////////
+// FunctionResult, FunctionState
+////////////////////////////////////////////////////////////////////////////////
+
+/// A result that instructs the VM what to do after a function finishes its execution.
+#[derive(Debug)]
+pub enum FunctionResult {
+    /// Take this value and push it on the stack as its return value.
+    ReturnPush(ObjP),
+
+    /// Return value has already been pushed to the stack.
+    Return,
+
+    /// Yield control to the VM with a state marker, and resume execution.
+    ///
+    /// This means that a new stack frame should have been pushed to the VM and resume execution
+    /// starting from there.
+    Yield(usize),
+}
+
+impl From<ObjP> for FunctionResult {
+    fn from(other: ObjP) -> Self {
+        FunctionResult::ReturnPush(other)
+    }
+}
+
+/// A function's resume state.
+///
+/// When a builtin function is called, it may need to set up a stack frame for a new function,
+/// yielding its control back to the VM. If it does this, then presumably, that function would like
+/// to resume its execution where it left off. There's not really a way to capture a native
+/// function's execution state in Rust (without tons of unsafe and not-really-worth-it black
+/// magic), so instead a builtin function will accept a `FunctionState` value to give it a hint of
+/// where it left off.
+#[derive(Debug, Clone, Copy)]
+pub enum FunctionState {
+    Begin,
+    Resume(usize),
+}
 
 ////////////////////////////////////////////////////////////////////////////////
 // BuiltinFunctionInst
 ////////////////////////////////////////////////////////////////////////////////
 
-pub type BuiltinFunctionPtr = fn(vm: &mut Vm, args: Vec<ObjP>) -> ObjP;
+pub type BuiltinFunctionPtr = fn(vm: &mut Vm, function_state: FunctionState) -> FunctionResult;
 
 #[derive(Debug, Trace)]
 pub struct BuiltinFunctionInst {
     base: BaseObjInst,
-    name: String,
+    #[unsafe_ignore_trace]
+    name: Rc<String>,
     #[unsafe_ignore_trace]
     function: BuiltinFunctionPtr,
     arity: Argc,
@@ -27,7 +68,7 @@ impl BuiltinFunctionInst {
     pub fn new(name: impl ToString, function: BuiltinFunctionPtr, arity: Argc) -> Self {
         Self {
             base: Default::default(),
-            name: name.to_string(),
+            name: Rc::new(name.to_string()),
             function,
             arity,
         }
@@ -66,16 +107,12 @@ impl Obj for BuiltinFunctionInst {
     }
 
     fn call(&self, vm: &mut Vm, argc: Argc) {
-        // args
-        let mut args = Vec::with_capacity(argc as usize);
-        for _ in 0..argc {
-            args.push(vm.pop());
-        }
-        args.reverse();
-        // callee (self)
-        vm.pop();
-        let result = (self.function)(vm, args);
-        vm.push(result);
+        let new_frame = Frame::new(
+            Rc::clone(&self.name),
+            Function::Builtin(self.function, FunctionState::Begin),
+            vm.stack().len() - (argc as usize),
+        );
+        vm.push_frame(new_frame);
     }
 
     fn equals(&self, other: &dyn Obj) -> bool {
@@ -159,12 +196,11 @@ impl Obj for UserFunctionInst {
 
     fn call(&self, vm: &mut Vm, argc: Argc) {
         assert_eq!(argc, self.arity, "argc must match arity");
-        let new_frame = Frame {
-            name: Rc::clone(&self.name),
-            chunk: Rc::clone(&self.chunk),
-            ip: 0,
-            stack_base: vm.stack().len() - (argc as usize),
-        };
+        let new_frame = Frame::new(
+            Rc::clone(&self.name),
+            Function::Chunk(Rc::clone(&self.chunk)),
+            vm.stack().len() - (argc as usize),
+        );
         vm.push_frame(new_frame);
         for capture in &self.captures {
             vm.push(capture.clone());