starting to clear up slots

mostly docs

lib/register/instructions/load_constant.rb

@@ -1,7 +1,7 @@
 module Register
   # load a constant into a register
   #
-  # first arguemnt is the register the constant is loaded into
+  # first argument is the register the constant is loaded into
   # second is the actual constant
 
   class LoadConstant < Instruction

lib/register/register_machine.rb

@@ -4,3 +4,7 @@ require_relative "assembler"
 require_relative "passes/set_implementation"
 require_relative "passes/return_implementation"
 require_relative "passes/call_implementation"
+
+# So the memory model of the machine allows for indexed access into an "object" .
+# A fixed number of objects exist (ie garbage collection is reclaming, not destroying and
+#  recreating) although there may be a way to increase that number.

lib/virtual/machine.rb

@@ -1,8 +1,5 @@
 module Virtual
-  # The Virtual Machine is a value based virtual machine in which ruby is implemented.
-  # While it is value based, it resembles oo in basic ways of object encapsulation and method
-  # invocation, it is a "closed" / static sytem in that all types are know and there is no
-  # dynamic dispatch (so we don't bite our tail here).
+  # The Virtual Machine is a object based virtual machine in which ruby is implemented.
   #
   # It is minimal and realistic and low level
   # - minimal means that if one thing can be implemented by another, it is left out. This is quite
@@ -10,17 +7,13 @@ module Virtual
   # - realistic means it is easy to implement on a 32 bit machine (arm) and possibly 64 bit.
   #     Memory access,some registers of same size are the underlying hardware. (not ie byte machine)
   # - low level means it's basic instructions are realively easily implemented in a register machine.
-  #      ie send is not a an instruction but a function.
+  #      Low level means low level in oo terms though, so basic instruction to implement oo
+  #  #
+  # The ast is transformed to virtual-machine objects, some of which represent code, some data.
   #
-  # So the memory model of the machine allows for indexed access into an "object" .
-  # A fixed number of objects exist (ie garbage collection is reclaming, not destroying and
-  #  recreating) although there may be a way to increase that number.
+  # The next step transforms to the register machine layer, which is quite close to what actually
+  #  executes. The step after transforms to Arm, which creates executables.
   #
-  # The ast is transformed to virtaul-machine objects, some of which represent code, some data.
-  #
-  # The next step transforms to the register machine layer, which is what actually executes.
-  #
-
   # More concretely, a virtual machine is a sort of oo turing machine, it has a current instruction,
   # executes the instructions, fetches the next one and so on.
   # Off course the instructions are not soo simple, but in oo terms quite so.
@@ -28,16 +21,23 @@ module Virtual
   # The machine is virtual in the sense that it is completely modeled in software,
   # it's complete state explicitly available (not implicitly by walking stacks or something)
 
-  # The machine has a no register, but local variables, a scope at each point in time.
-  # Scope changes with calls and blocks, but is saved at each level. In terms of lower level
-  #  implementation this means that the the model is such that what is a variable in ruby,
-  #  never ends up being just on the pysical stack.
+  # The machine has a no register, but objects that represent it's state. There are four
+  # - message : the currently executing message (See Parfait::Message)
+  # - receiver : or self.  This is actually an instance of Message, but "hoisted" out
+  # -  frame : A pssible frame for temporary data. Also part of the message and "hoisted" out
+  # - next_message: A message object that the current activation wants to send.
   #
+  # Messages form a linked list (not a stack) and the Space is responsible for storing
+  # and handing out empty messages
+  #
+  # The "machine" is not part of the run-time (Parfait)
+
   class Machine
 
+    FIRST_PASS = "Virtual::SendImplementation"
     def initialize
       @parser  = Parser::Salama.new
-      @passes = [ "Virtual::SendImplementation" ]
+      @passes = [  FIRST_PASS ]
       @objects = []
       @booted = false
     end
@@ -82,8 +82,8 @@ module Virtual
     # as before, run all passes that are registered
     # (but now finer control with before/after versions)
     def run_passes
-      run_before "Virtual::SendImplementation"
-      run_after "Virtual::SendImplementation"
+      run_before FIRST_PASS
+      run_after FIRST_PASS
     end
 
     # Objects are data and get assembled after functions

lib/virtual/slots/frame_slot.rb

@@ -0,0 +1,12 @@
+module Virtual
+
+  # Slots in the Frame a re represented by instances of FrameSlot
+
+  # Slots in the Frame are local or temporary varialbes in a message
+  class FrameSlot < Slot
+    def initialize index , type = Unknown, value = nil
+      super
+    end
+  end
+
+end

lib/virtual/slots/message_slot.rb

@@ -1,5 +1,20 @@
 module Virtual
-  # The message that is being processed has a layout as per the constant above
+
+  MESSAGE_CALLER = 0
+  MESSAGE_RETURN_ADDRESS = 1
+  MESSAGE_EXCEPTION_ADDRESS = 2
+  MESSAGE_SELF = 3
+  MESSAGE_NAME = 4
+  MESSAGE_RETURN_VALUE = 5
+  MESSAGE_FRAME = 6
+  MESSAGE_PAYLOAD = 7
+
+  # The current Message is one of four objects the virtual machine knows
+  #
+  # Slots represent instance variables of objects, so MessageSlots
+  # represent instance variables of Message objects.
+  # The Message has a layout as per the constant above
+
   class MessageSlot < Slot
     def initialize index , type = Unknown , value = nil
       super(index ,type , value )

lib/virtual/slots/self_slot.rb

@@ -0,0 +1,21 @@
+module Virtual
+
+  # Self (the receiver of the current message) is a Slot in the Message.
+  # The current self in the current message and if the current message
+  # want to send a message it puts the new self into the next_message.
+  #
+  # The slot in the Message is represented by instances of class Self
+  # (and slots in the next_message by instances of NewSelf)
+  #
+  #  Additionally the current Self is represented as it's own top-level object.
+  # If self is an Object one can refer to it's instance variables as Slots in SelfSlot
+  #
+  # In Summary: class Self represents the self object and SelfSlot instances variables of
+  #  that object
+  #
+  class SelfSlot < Slot
+    def initialize index , type = Unknown, value = nil
+      super
+    end
+  end
+end

lib/virtual/slots/slot.rb

@@ -2,7 +2,7 @@ module Virtual
   # A slot is a slot in an object. It is the storage location for a value.
   #             (Remember, values are typed)
   # From a memory perspective a slot is an index into an array (the object)
-  # But we are not modelling the array here, but the index into it.
+  # We are not modelling the array here, but the index into it.
 
   # Four known objects exist and those correspond to subclasses:
   # - the message that has been received: MessageSlot
@@ -21,15 +21,6 @@ module Virtual
     FRAME_REGISTER = :r2
     NEW_MESSAGE_REGISTER = :r3
 
-    MESSAGE_CALLER = 0
-    MESSAGE_RETURN_ADDRESS = 1
-    MESSAGE_EXCEPTION_ADDRESS = 2
-    MESSAGE_SELF = 3
-    MESSAGE_NAME = 4
-    MESSAGE_RETURN_VALUE = 5
-    MESSAGE_FRAME = 6
-    MESSAGE_PAYLOAD = 7
-
     attr_accessor :index , :type , :value
 
     private #abstract base class
@@ -41,19 +32,9 @@ module Virtual
     end
   end
 
-  class FrameSlot < Slot
-    def initialize index , type = Unknown, value = nil
-      super
-    end
-  end
-
-  class SelfSlot < Slot
-    def initialize index , type = Unknown, value = nil
-      super
-    end
-  end
-
 end
 
 require_relative "message_slot"
+require_relative "self_slot"
+require_relative "frame_slot"
 require_relative "new_message_slot"