From fdb3fbc82599504648c1d2d6087a1e9cca29f690 Mon Sep 17 00:00:00 2001
From: Torsten Ruger <torsten@villataika.fi>
Date: Wed, 8 Apr 2015 20:24:50 +0300
Subject: [PATCH] Parfait documentation

outline of expanded parfait, documented but not coded
---
 lib/parfait/class.rb  | 16 ++++++++++++++++
 lib/parfait/frame.rb  |  5 +++++
 lib/parfait/layout.rb | 31 +++++++++++++++++++++++++++++++
 lib/parfait/object.rb | 21 ++++++++++++++++++---
 lib/parfait/page.rb   | 10 ++++++++++
 lib/parfait/space.rb  | 10 ++++++++++
 lib/parfait/value.rb  | 37 +++++++++++++++++++++++++++++++++++++
 7 files changed, 127 insertions(+), 3 deletions(-)
 create mode 100644 lib/parfait/layout.rb
 create mode 100644 lib/parfait/value.rb

diff --git a/lib/parfait/class.rb b/lib/parfait/class.rb
index aa574743..c6f712e0 100644
--- a/lib/parfait/class.rb
+++ b/lib/parfait/class.rb
@@ -1,2 +1,18 @@
+
+# A class describes the capabilities of an object, ie what data it has
+# and functions it responds to
+#
+# An Object carries the data for the instance variables it has
+# The Layout lists the names of the instance variables
+# The class keeps a list of instance methods, these have a name and code
+# The class also keeps a list of class methods (with names+code)
+# Class methods are instance methods on the class object
+
+# So it is essential that the class (the object defining the class)
+# can carry methods. It does so as instance variables.
+# In fact this property is implemented in the Object, as methods
+# may be added to any object at run-time
+
 class Class
+
 end
diff --git a/lib/parfait/frame.rb b/lib/parfait/frame.rb
index af331caf..49edb173 100644
--- a/lib/parfait/frame.rb
+++ b/lib/parfait/frame.rb
@@ -1,4 +1,9 @@
 
+# A Frame is set up by functions that use local variables or temporary variables
+# in fact temporary variables are local variables named by the system
+
+# It allows for access to those variables basically 
+
 class Frame
   
 end
diff --git a/lib/parfait/layout.rb b/lib/parfait/layout.rb
new file mode 100644
index 00000000..2a58f4b9
--- /dev/null
+++ b/lib/parfait/layout.rb
@@ -0,0 +1,31 @@
+# An Object is really a hash like structure. It is dynamic and
+# you want to store values by name.
+# One could (like mri), store the names in each object, but that is wasteful
+# Instead we store only the values, and access them by index.
+# The Layout allows the mapping of names to index.
+
+# The Layout of an object describes the memory layout of the object
+# The Layout is a simple list of the names of instance variables.
+# 
+# As every object has a Layout to describe it, the name "layout" is the 
+# first name in the list for every Layout.
+# But as we want every Object to have a class, this is the second
+# entry in the list. The name for the entry is "object_class"
+
+# In other words, the Layout is a list of names that describe
+# the values stored in an actual object.
+# The object is an array of values of length n and 
+# the Layout is an array of names of length n
+# Together they turn the object into a hash like structure 
+
+class Layout < Object
+
+  # given a name as symbol, return the integer index of that entry
+  # we use 0 as "not found" as we don't want negatives, and can't raise
+  # luckily 0 is always the type-word in an object and so by returning
+  # one-offsets we can use the return value straight without adding 1
+  def index_of( name )
+    #internal implementation....
+  end
+
+end
diff --git a/lib/parfait/object.rb b/lib/parfait/object.rb
index e63c18a5..6a0d9d8c 100644
--- a/lib/parfait/object.rb
+++ b/lib/parfait/object.rb
@@ -1,9 +1,24 @@
-# this is not a "normal" ruby file, ie it is not required by salama
-# instead it is parsed by salama to define part of the program that runs
+# to be precise, this should be an ObjectReference, as the Reference is a Value
+# but we don't want to make that distinction all the time , so we don't.
 
-class Object
+# that does lead to the fact that we have Reference functions on the Object though 
 
+class Object < Value
+
+  def get_type()
+    OBJECT_TYPE
+  end
+
+  # This is the crux of the object system. The class of an object is stored in the objects
+  # memory (as opposed to an integer that has no memory and so always has the same class)
+  #
+  # In Salama we store the class in the Layout, and so the Layout is the only fixed
+  # data that every object carries.
   def get_class()
     @layout.get_class()
   end
+
+  def get_layout()
+    @layout
+  end
 end
diff --git a/lib/parfait/page.rb b/lib/parfait/page.rb
index d686659c..51802eb4 100644
--- a/lib/parfait/page.rb
+++ b/lib/parfait/page.rb
@@ -1,3 +1,13 @@
 
+# A Page (from the traditionally a memory page) represents a collection of
+# objects in a physically form. Ie the page holds the memory or data, that
+# the objects are made up of.
+
+# Pages have a total size, but more importantly and object size.
+# All objects of a Page are same sized, and multiples of the smallest
+# object. The smallest object is usually a cache line, 16 bytes or
+# an exponent of two larger.
+
 class Page
+
 end
diff --git a/lib/parfait/space.rb b/lib/parfait/space.rb
index 88e52830..e3c03b8e 100644
--- a/lib/parfait/space.rb
+++ b/lib/parfait/space.rb
@@ -1,3 +1,13 @@
 
+# A Space is a collection of pages. It stores objects, the data for the objects,
+# not references. See Page for more detail.
+
+# Pages are stored by the object size they represent in a hash.
+
+# Space and Page work together in making *new* objects available.
+# "New" is slightly misleading in that normal operation only ever
+# recycles objects.
+
 class Space
+
 end
diff --git a/lib/parfait/value.rb b/lib/parfait/value.rb
new file mode 100644
index 00000000..0d15e0fc
--- /dev/null
+++ b/lib/parfait/value.rb
@@ -0,0 +1,37 @@
+# this is not a "normal" ruby file, ie it is not required by salama
+# instead it is parsed by salama to define part of the program that runs
+
+# Values are _not_ objects. Specifically they have the following properties not found in objects:
+# - they are immutable
+# - equality implies identity == is ===
+# - they have type, not class
+
+# To make them useful in an oo system, we assign a class to each basic type
+# This makes them look more like objects, but they are not.
+
+# Value is an abstract class that unifies the "has a type" concept
+# Types are not "objectified", but are represented as integer constants
+
+class Value
+
+  # to make the machine work, the constants need
+  # - to start at 0
+  # - be unique
+  # - be smaller enough to fit into the 2-4 bits available 
+  INTEGER_VALUE = 0
+  OBJECT_VALUE  = 1
+  
+  # the type is what identifies the value
+  def get_type()
+    raise "abstract clalled on #{self}"
+  end
+
+  # Get class works on the type. The value's type is stored by the machine.
+  # So this function is not overriden in derived classes, because it is used
+  # to espablish what class a value has! (it's that "fake" oo i mentioned)
+  def get_class()
+    type = self.get_type()
+    return Integer if( type == INTEGER_VALUE )
+    raise "invalid type"
+  end
+end