lots of comments

Author: http://jneen.net/

lib/magvm/actions.py

@@ -24,6 +24,16 @@ def inst_action(fn):
 
     return fn
 
+
+################## actions! #################
+# These functions implement the instructions
+# of the vm, and are run by a Frame whenever
+# it encounters the corresponding instruction.
+#
+# see inst.py for descriptions of these.
+# see frame.py, specifically the .step() method
+#     to see how they're called.
+
 @inst_action
 def pop(frame, args):
     frame.stack.pop()

lib/magvm/env.py

@@ -1,6 +1,21 @@
 from value import *
 from symbol import revsym
 
+############ environments ###############
+# An environment in Magritte is a simple
+# dictionary of keys and values, together
+# with a parent pointer (a "prototype").
+# These are used not only for variable
+# scopes, but also for all OOP-style
+# patterns.
+#
+# An environment additionally contains
+# input and output channels, which can
+# be inherited.
+#
+# see frame.py for how the channels are used
+# see actions.py and intrinsics.py for
+# the basic operations from the machine.
 MAX_CHANNELS = 8
 class Env(Value):
     def __init__(self, parent=None):

lib/magvm/frame.py

@@ -7,6 +7,24 @@
 from actions import inst_actions
 from value import *
 
+################# frame #####################
+# This class represents a stack frame inside
+# a single process. It contains a program
+# counter which points to the current
+# instruction, and an environment holding the
+# variables in its local scope.
+#
+# The frame also represents the main API for
+# intrinsics and instructions (actions) to
+# change the state of the machine - the
+# current frame is always passed in to their
+# implementations.
+#
+# see env.py for environments
+# see proc.py for the process
+# see actions.py and intrinsic.py for
+#     the use of many of these methods
+
 class Frame(object):
     def crash(self, message):
         assert isinstance(message, Status)

lib/magvm/inst.py

@@ -55,6 +55,18 @@ def mkinst(name, *a):
     screaming_name = name.upper().replace('-', '_')
     setattr(InstType, screaming_name, t.id)
 
+############# instruction documentation ###############
+# mkinst(instruction_name, argument_types, start_stack, end_stack, description)
+#
+# The argument types are needed at runtime for loading
+# files, so we can re-index them according to the global
+# tables. For example, in a compiled .magc file a `jump`
+# instruction may refer to an address within the file -
+# but once all instructions are merged together into a
+# global table it will need to refer to a different number.
+#
+# see actions.py for the implementations of these.
+
 # jumps and spawns
 mkinst('frame', ['inst'], ['env'], [], 'start a new frame')
 mkinst('return', [], [], [], 'pop a frame off the stack')

lib/magvm/machine.py

@@ -19,6 +19,9 @@
 jit_driver = JitDriver(greens=['pc'], reds=['env', 'stack'])
 
 ################## machine ####################
+# This class contains the main loop of the vm,
+# and implements basic scheduling among a
+# collection of Proc objects.
 class Machine(object):
     def __init__(self):
         self.procs = Table()

lib/magvm/proc.py

@@ -8,13 +8,19 @@
 from debug import debug, open_shell
 from value import *
 
+############# processes #######################
+# This class represents one process, running
+# concurrently with others. It is ticked forward
+# one step at a time by the machine through the
+# .step() method. This method tries to evaluate
+# as much as it can before it is set to wait.
 class Proc(TableEntry):
-    INIT = 0
-    RUNNING = 1
-    WAITING = 2
-    INTERRUPTED = 3
-    DONE = 4
-    TERMINATED = 5
+    INIT = 0        # hasn't started running yet
+    RUNNING = 1     # can safely step forward
+    WAITING = 2     # waiting to be woken up by a channel
+    INTERRUPTED = 3 # the waiting channel has closed, need to unwind the stack
+    DONE = 4        # no more steps to run
+    TERMINATED = 5  # there has been a crash, probably due to an error
 
     def set_init(self): self.state = Proc.INIT
     def set_running(self): self.state = Proc.RUNNING
@@ -23,9 +29,10 @@ def set_interrupted(self): self.state = Proc.INTERRUPTED
     def set_done(self): self.state = Proc.DONE
     def set_terminated(self): self.state = Proc.TERMINATED
 
-    # important: a channel will set a successful write to "running". but
-    # if that write pipes into a closed channel it will properly get set to
-    # INTERRUPTED and we want to avoid overriding that.
+    # Important: a channel will set a successful write to "running". but
+    # if that write is connected to a closed channel, it needs to preserve
+    # the INTERRUPTED state. So on a successful read or write, we only set
+    # the state back to RUNNING if we can verify it's still WAITING.
     def try_set_running(self):
         if self.state == Proc.WAITING:
             debug(0, ['try_set_running: set to running', self.s()])
@@ -54,6 +61,11 @@ def __init__(self, machine):
         self.status = Success()
         self.last_cleaned = []
 
+    # Push a new frame on to the call stack, with a given environment
+    # and starting instruction. This will automatically tail eliminate
+    # any finished frames from the top. However, this can be disabled on
+    # a case-by-case basis by the `tail_elim` parameter for things like
+    # loading files, where we need to preserve the base environment.
     def frame(self, env, addr, tail_elim=True):
         debug(0, ['--', str(self.id), labels_by_addr[addr].name])
         assert isinstance(addr, int)
@@ -65,16 +77,20 @@ def frame(self, env, addr, tail_elim=True):
 
         if tail_elim:
             eliminated = self.tail_eliminate()
-            if eliminated:
-                frame.env = eliminated.env.merge(env)
-                for comp in eliminated.compensations:
+
+            # when we eliminate a frame, we need to preserve
+            # its stack variables and compensations for the
+            # new frame.
+            for e in eliminated:
+                frame.env = e.env.merge(frame.env)
+                for comp in e.compensations:
                     frame.compensations.append(comp)
 
         self.frames.append(frame)
         return frame
 
     def tail_eliminate(self):
-        out = None
+        out = []
 
         # don't tail eliminate the root frame, for Reasons.
         # the root frame might have the global env and we really don't want
@@ -83,7 +99,7 @@ def tail_eliminate(self):
 
         while len(self.frames) > 1 and self.current_frame().should_eliminate():
             debug(0, ['-- tco', self.s()])
-            out = self.pop()
+            out.append(self.pop())
 
         debug(0, ['-- post-tco', self.s()])
 
@@ -99,9 +115,6 @@ def pop(self):
 
     def step(self):
         debug(0, ['=== step %s ===' % self.s()])
-        # if not self.frames:
-        #     debug(0, ['-- out of frames', self.s()])
-        #     self.set_done()
 
         if self.frames:
             env = self.current_frame().env

lib/magvm/symbol.py

@@ -1,5 +1,7 @@
 from table import Table, TableEntry
 
+#### the global symbol table ####
+
 class SymbolTable(Table):
     def sym(self, string):
         assert isinstance(string, str)

lib/magvm/targetmagritte.py

@@ -5,6 +5,10 @@
 from rpython.rlib.objectmodel import we_are_translated
 import os
 
+####### main target ##########################
+# This is the main target file for compilation by RPython.
+# The whole program will start at the `entry_point` function.
+
 def run_file(filename):
     load_file(filename)
     machine.spawn_label(base_env, 'main')

lib/magvm/value.py

@@ -5,6 +5,22 @@
 
 from rpython.rlib.rarithmetic import r_uint, intmask
 
+######### values! ###########################
+# These classes implement the core values of
+# the VM. They can implement a number of interfaces
+# through the @impl function - attached objects
+# that implement certain features. For example,
+# many values can be invoked as functions, and
+# the behaviour is implemented in value.invokable.
+# This allows us to keep the top-level shared
+# namespace thin.
+#
+# Since RPython's support for __repr__ can be
+# brittle, we equip each class with a method
+# .s() to retrieve the string representation.
+#
+# see channel.py for the Channel value.
+
 class Done(Exception): pass
 class Deadlock(Exception): pass