runtime: Introduce the locals stack + use it for (inline) methods/blocks

This is a bit of a large commit because the changes are all
interconnected. The main idea is that now, instead of getting locals
from the activation object, we have a "locals stack" that is responsible
for storing all of the locals that are used by the various activations.

Every time a method is activated, the method needs to allocate some
space on the locals stack. This space is the total count of all locals
used by the method itself, and any inline methods/blocks defined
within (as blocks/inline methods also have access to the method's
locals).

To calculate all of the locals required, AstGen now has the
ObjectDescriptorLink struct which is weaved through code generation and
calculates the local index for each local that's accessible from a given
activation within a containing method. The sum is then recorded on the
CreateMethod instruction, and when the method is activated, the locals
stack gets the memory reserved.

The GetLocal/PutLocal instructions now offset into the locals stack
instead of using the activation object. In essence, we no longer use any
of the assignable slot values of the activation object itself anymore.

This gives us -15% wall clock time on the Fibonacci example, on top of
the -18.5% wall clock time with the initial locals implementation,
bringing the total performance boost of locals to -31% or 1.45x which is
pretty huge.

Note that because we still create the activation object, we currently
have to copy the assignable and argument slot values to the locals
stack, so there is still a lot of performance gains to be had. When
constants are obtainable without going through the activation object,
and the activation object is completely removed, the arguments will be
used directly off the argument stack instead of being copied which
should bring a further performance boost.

Author: sin-ack

src/runtime/Activation.zig

@@ -31,12 +31,17 @@ target_location: bytecode.RegisterLocation,
 /// block's own activation object. Not used with methods, since we don't want to
 /// inherit previous activation objects in methods (that would make the language
 /// dynamically scoped :^).
+// TODO: To be removed when the activation object is removed, as we will no
+//       longer perform lookups through the activation chain.
 parent_activation: ?ActivationRef = null,
 /// Will be used as the target activation that a non-local return needs to rise
 /// to. Must be non-null when a non-local return is encountered, and when
 /// non-null, must point to an activation where
 /// `nonlocal_return_target_activation` is null.
 nonlocal_return_target_activation: ?ActivationRef = null,
+/// The offset within the local stack where this activation's local variables
+/// start. "Local 0" is reserved for the receiver of the method or block.
+local_stack_offset: u32,
 
 // --- Activation creation info ---
 
@@ -64,6 +69,7 @@ pub fn initInPlace(
     target_location: bytecode.RegisterLocation,
     creator_message: ByteArray,
     created_from: SourceRange,
+    local_stack_offset: u32,
 ) void {
     self.* = .{
         .activation_id = newActivationID(),
@@ -72,6 +78,7 @@ pub fn initInPlace(
         .stack_snapshot = context.getVM().takeStackSnapshot(),
         .creator_message = creator_message,
         .created_from = created_from.copy(),
+        .local_stack_offset = local_stack_offset,
     };
 }
 
@@ -226,9 +233,14 @@ pub const ActivationStack = struct {
         );
         defer token.deinit();
 
+        // FIXME: Eventually top-level activations will have locals too, so this will be invalid.
+        //        We should instead receive method objects here, and reserve space in the actor's
+        //        locals stack.
+        const local_stack_offset: u32 = @intCast(vm.current_actor.locals_stack.height());
+
         const toplevel_context_method = try MethodObject.createTopLevelContextForExecutable(vm.allocator, &vm.heap, &token, new_executable, new_executable.value.getEntrypointBlock());
         const activation_slot = try self.getNewActivationSlot(vm.allocator);
-        toplevel_context_method.activateMethod(&token, context.getActor().id, vm.lobby_object, &.{}, target_location, source_range, activation_slot);
+        toplevel_context_method.activateMethod(&token, context.getActor().id, vm.lobby_object, &.{}, target_location, source_range, activation_slot, local_stack_offset);
     }
 };
 

src/runtime/Actor.zig

@@ -58,6 +58,18 @@ register_file: bytecode.lowcode.RegisterFile = .{},
 argument_stack: ArgumentStack = .{},
 saved_register_stack: Stack(SavedRegister, "Saved register stack", false) = .{},
 
+/// The locals for each method activation on this actor. Each method activation
+/// stores its own set of locals here when activated.
+///
+/// For each method, the locals are laid out as follows:
+///
+/// [receiver][method local 0]...[method local N]
+///
+/// The total number of locals for a method is the maximum number of possible locals
+/// that can be used at any point during the method's execution, which is the
+/// deepest block local depth. Some locals may be unused at certain points during
+/// execution, and blocks can reuse locals from their parent blocks.
+locals_stack: Stack(Value, "Locals stack", false) = .{},
 
 /// The currently active source range. This is updated by the source_range
 /// instruction.
@@ -81,6 +93,7 @@ pub const StackSnapshot = struct {
     argument_height: usize,
     argument_sentinel_height: ArgumentStack.SentinelIndex,
     saved_register_height: usize,
+    locals_height: usize,
 
     /// Bump just the argument stack height. This is necessary because the stack
     /// snapshot for an activation is created while the stack still contains the
@@ -210,6 +223,7 @@ fn init(self: *Actor, actor_object: ActorObject.Ptr) void {
 fn deinit(self: *Actor, allocator: Allocator) void {
     self.clearMailbox(allocator);
 
+    self.locals_stack.deinit(allocator);
     self.argument_stack.deinit(allocator);
     self.saved_register_stack.deinit(allocator);
 
@@ -221,24 +235,39 @@ fn deinit(self: *Actor, allocator: Allocator) void {
 
 pub fn activateMethod(
     self: *Actor,
+    vm: *VirtualMachine,
     token: *heap.AllocationToken,
     method: MethodObject.Ptr,
+    arguments: []const Value,
     target_location: bytecode.RegisterLocation,
     source_range: SourceRange,
 ) !void {
-    return try self.activateMethodWithContext(token, self.actor_object.get().context, method, target_location, source_range);
+    return try self.activateMethodWithContext(vm, token, self.actor_object.get().context, method, arguments, target_location, source_range);
 }
 
 pub fn activateMethodWithContext(
     self: *Actor,
+    vm: *VirtualMachine,
     token: *heap.AllocationToken,
     actor_context: Value,
     method: MethodObject.Ptr,
+    arguments: []const Value,
     target_location: bytecode.RegisterLocation,
     source_range: SourceRange,
 ) !void {
+    // HACK: Transitional code. Copy initial assignable slot values and
+    //       arguments into the new activation's local stack.
+    const assignable_slot_count = method.getMap().getAssignableSlotCount();
+    const argument_slot_count = method.getMap().getArgumentSlotCount();
+
+    // NOTE: +1 because local 0 is reserved for the receiver.
+    const local_stack_offset = try self.locals_stack.reserveSpace(vm.allocator, @intCast(method.getMap().local_depth.get() + 1), vm.global_nil);
+    self.locals_stack.allItems()[local_stack_offset] = actor_context;
+    @memcpy(self.locals_stack.allItems()[local_stack_offset + 1 .. local_stack_offset + 1 + assignable_slot_count], method.getAssignableSlots());
+    @memcpy(self.locals_stack.allItems()[local_stack_offset + 1 + assignable_slot_count .. local_stack_offset + 1 + assignable_slot_count + argument_slot_count], arguments);
+
     const activation_slot = try self.activation_stack.getNewActivationSlot(context.getVM().allocator);
-    method.activateMethod(token, self.id, actor_context, &.{}, target_location, source_range, activation_slot);
+    method.activateMethod(token, self.id, actor_context, arguments, target_location, source_range, activation_slot, @intCast(local_stack_offset));
 }
 
 pub fn pushContext(self: *Actor) void {
@@ -270,9 +299,7 @@ pub fn execute(self: *Actor) !ActorResult {
             defer token.deinit();
             method = message.method.get();
 
-            const actor_context = self.actor_object.get().context;
-            const new_activation = try self.activation_stack.getNewActivationSlot(vm.allocator);
-            method.activateMethod(&token, self.id, actor_context, message.arguments, .zero, message.source_range, new_activation);
+            try self.activateMethod(vm, &token, method, message.arguments, .zero, message.source_range);
 
             self.message_sender = message.sender;
 
@@ -379,12 +406,14 @@ pub fn takeStackSnapshot(self: Actor) StackSnapshot {
         .argument_height = self.argument_stack.height(),
         .argument_sentinel_height = self.argument_stack.sentinelHeight(),
         .saved_register_height = self.saved_register_stack.height(),
+        .locals_height = self.locals_stack.height(),
     };
 }
 
 pub fn restoreStackSnapshot(self: *Actor, snapshot: StackSnapshot) void {
     self.argument_stack.restoreTo(snapshot.argument_height, snapshot.argument_sentinel_height);
     self.saved_register_stack.restoreTo(snapshot.saved_register_height, {});
+    self.locals_stack.restoreTo(snapshot.locals_height, {});
 }
 
 pub fn readRegister(self: Actor, location: bytecode.RegisterLocation) Value {
@@ -428,6 +457,10 @@ pub fn visitEdges(
         try visitor.visit(&saved_register.value, null);
     }
 
+    for (self.locals_stack.allItems()) |*local| {
+        try visitor.visit(local, null);
+    }
+
     {
         var it = self.mailbox.first;
         while (it) |node| : (it = node.next) {
@@ -451,6 +484,7 @@ pub fn unwindStacks(self: *Actor) void {
 
     self.argument_stack.restoreTo(0, if (ArgumentStackHasSentinel) 0 else {});
     self.saved_register_stack.restoreTo(0, {});
+    self.locals_stack.restoreTo(0, {});
 }
 
 pub fn putMessageInMailbox(

src/runtime/Interpreter.zig

@@ -311,6 +311,7 @@ pub fn execute(self: *Interpreter) Error!Actor.ActorResult {
                 executable.value.getObjectDescriptor(payload.descriptor_index),
                 payload.block_index,
                 payload.is_inline,
+                payload.local_depth,
             );
             self.vm.writeRegister(block.getTargetLocation(index), object.asValue());
 
@@ -331,6 +332,7 @@ pub fn execute(self: *Interpreter) Error!Actor.ActorResult {
                 executable,
                 executable.value.getObjectDescriptor(payload.descriptor_index),
                 payload.block_index,
+                payload.method_local_offset,
             );
             self.vm.writeRegister(block.getTargetLocation(index), object.asValue());
 
@@ -388,12 +390,9 @@ pub fn execute(self: *Interpreter) Error!Actor.ActorResult {
             const block = self.getCurrentBytecodeBlock();
             const index = self.getInstructionIndex();
 
-            const receiver: ActivationObject.Ptr = self.actor.activation_stack.getCurrent().activation_object.get();
-            const local_index = block.getTypedPayload(index, .GetLocal).local_index;
-
-            // TODO: Transitional code. Eventually we will eliminate the activation
-            //       object entirely.
-            const value = receiver.getAssignableSlotFromLocalIndex(local_index).*;
+            const local_stack_offset = self.getCurrentActivation().local_stack_offset;
+            const local_index = block.getTypedPayload(index, .GetLocal).local_index.get();
+            const value = self.actor.locals_stack.allItems()[local_stack_offset + local_index];
             self.vm.writeRegister(block.getTargetLocation(index), value);
 
             _ = self.getCurrentActivation().advanceInstruction();
@@ -410,15 +409,14 @@ pub fn execute(self: *Interpreter) Error!Actor.ActorResult {
             const receiver: ActivationObject.Ptr = self.actor.activation_stack.getCurrent().activation_object.get();
             const payload = block.getTypedPayload(index, .PutLocal);
 
-            // TODO: Transitional code. Eventually we will eliminate the activation
-            //       object entirely.
-            const target_ptr = receiver.getAssignableSlotFromLocalIndex(payload.local_index);
+            const local_stack_offset = self.getCurrentActivation().local_stack_offset;
+            const local_index = payload.local_index.get();
             const value = self.vm.readRegister(payload.value_location);
 
             // David will remember that.
             _ = try self.vm.heap.rememberObjectReference(receiver.asValue(), value);
 
-            target_ptr.* = value;
+            self.actor.locals_stack.allItems()[local_stack_offset + local_index] = value;
             // Assignment messages return self!
             self.vm.writeRegister(block.getTargetLocation(index), receiver.asValue());
 
@@ -747,6 +745,9 @@ fn executeBlock(
 
     const parent_activation_object = block.getMap().parent_activation.get(self.actor.activation_stack).?.activation_object;
     const activation_slot = try self.actor.activation_stack.getNewActivationSlot(self.vm.allocator);
+
+    // The method contains the locals of the block.
+    const method_stack_offset = block.getMap().nonlocal_return_target_activation.get(self.actor.activation_stack).?.local_stack_offset;
     block.activateBlock(
         &token,
         parent_activation_object.value,
@@ -755,9 +756,25 @@ fn executeBlock(
         try message_name.get(self.vm.allocator),
         source_range,
         activation_slot,
+        method_stack_offset,
     );
+
+    // HACK: Transitional code. Copy initial assignable slot values and
+    //       arguments into the new activation's local stack.
+    const assignable_slot_count = block.getMap().getAssignableSlotCount();
+    const argument_slot_count = block.getMap().getArgumentSlotCount();
+
+    // Our locals start after the method's locals.
+    // NOTE: +1 because local 0 is reserved for the receiver.
+    const local_stack_offset = method_stack_offset + 1 + @as(u32, @intCast(block.getMap().method_local_offset.get()));
+    @memcpy(self.actor.locals_stack.allItems()[local_stack_offset .. local_stack_offset + assignable_slot_count], block.getAssignableSlots());
+    @memcpy(self.actor.locals_stack.allItems()[local_stack_offset + assignable_slot_count .. local_stack_offset + assignable_slot_count + argument_slot_count], arguments);
 }
 
+// FIXME: While inline methods *are* methods in a technical sense, they are not
+//        initialized like normal methods because they don't have their own
+//        space on the locals stack. Perhaps they should be split into their own
+//        type/function?
 fn executeMethod(
     self: *const Interpreter,
     const_receiver: Value,
@@ -795,8 +812,37 @@ fn executeMethod(
         }
     }
 
+    const local_stack_offset = if (const_method.getMap().isInlineMethod())
+        // NOTE: Because an inline method is only visible from the method that
+        //       defines it, or any other blocks/inline methods defined within
+        //       it, the currently running activation MUST be one whose local
+        //       source is the method. Therefore, we can simply reuse the
+        //       current activation's local stack offset.
+        self.getCurrentActivation().local_stack_offset
+    else
+        // NOTE: +1 because local 0 is reserved for the receiver.
+        try self.actor.locals_stack.reserveSpace(self.vm.allocator, @intCast(method.getMap().local_depth.get() + 1), self.vm.global_nil);
+
     const activation_slot = try self.actor.activation_stack.getNewActivationSlot(self.vm.allocator);
-    method.activateMethod(&token, self.actor.id, receiver_of_method, arguments, target_location, source_range, activation_slot);
+    method.activateMethod(&token, self.actor.id, receiver_of_method, arguments, target_location, source_range, activation_slot, @intCast(local_stack_offset));
+
+    // HACK: Transitional code. Copy initial assignable slot values and
+    //       arguments into the new activation's local stack.
+    const assignable_slot_count = method.getMap().getAssignableSlotCount();
+    const argument_slot_count = method.getMap().getArgumentSlotCount();
+
+    const copy_base = if (method.getMap().isInlineMethod())
+        // For inline methods, the local_depth field is reinterpreted as
+        // the offset on top of the local stack offset.
+        local_stack_offset + 1 + method.getMap().local_depth.get()
+    else
+        local_stack_offset + 1;
+
+    if (!method.getMap().isInlineMethod()) {
+        self.actor.locals_stack.allItems()[local_stack_offset] = receiver_of_method;
+    }
+    @memcpy(self.actor.locals_stack.allItems()[copy_base .. copy_base + assignable_slot_count], method.getAssignableSlots());
+    @memcpy(self.actor.locals_stack.allItems()[copy_base + assignable_slot_count .. copy_base + assignable_slot_count + argument_slot_count], arguments);
 }
 
 fn createObject(
@@ -825,6 +871,7 @@ fn createMethod(
     object_descriptor: bytecode.ObjectDescriptor,
     block_index: u32,
     is_inline: bool,
+    local_depth: u32,
 ) !MethodObject.Ptr {
     const slot_count: u16 = @intCast(object_descriptor.slots.len);
     const byte_array_required_memory = slot_count * ByteArray.requiredSizeForAllocation();
@@ -847,6 +894,7 @@ fn createMethod(
         method_name,
         block,
         executable,
+        local_depth,
     );
     const method_object = MethodObject.create(&token, self.actor.id, method_map);
     try self.writeObjectSlots(MethodMap, &token, object_descriptor, method_map, method_object);
@@ -858,6 +906,7 @@ fn createBlock(
     executable: bytecode.Executable.Ref,
     object_descriptor: bytecode.ObjectDescriptor,
     block_index: u32,
+    method_local_offset: u32,
 ) !BlockObject.Ptr {
     const block = executable.value.getBlock(block_index);
     // The latest activation is where the block was created, so it will always
@@ -896,6 +945,7 @@ fn createBlock(
         nonlocal_return_target_activation,
         block,
         executable,
+        method_local_offset,
     );
     const block_object = BlockObject.create(&token, self.actor.id, block_map);
     try self.writeObjectSlots(BlockMap, &token, object_descriptor, block_map, block_object);

src/runtime/bytecode.zig

@@ -14,10 +14,12 @@ pub const lowcode = @import("./bytecode/lowcode.zig");
 
 /// Index of a local slot within an activation record.
 pub const LocalIndex = enum(u8) {
+    Receiver = 0,
     _,
 
-    pub fn init(value: u8) LocalIndex {
-        return @enumFromInt(value);
+    /// Initialize from a raw index value.
+    pub fn initIndex(index: u8) LocalIndex {
+        return @enumFromInt(index + 1);
     }
 
     pub fn get(self: LocalIndex) u8 {