Update examples

Author: xFrednet

examples/02-freezing.frank

@@ -9,8 +9,8 @@ freeze(x)
 # Assigning to a field of `x` afterward will throw an error
 # x.field = {} # ERROR
 
-# Mutability only applies to the value variables pointing to
-# immutable data can be reassigned.
+# Calling `freeze(x)` freezes the object `x` points to but not the variable
+# itself, so x can be reassigned
 x = {}
 x.f = {} # Mutation of x
 
@@ -20,9 +20,9 @@ x.f = {} # Mutation of x
 freeze(x)
 
 # The immutable status in Lungfish refers to the observable state.
-# This means that the reference can remain mutable as long as it is
-# not observable in the program. Notice how this new reference
-# increases the reference count.
+# This means that the reference count can remain mutable as long as
+# it is not observable in the program. Notice how this new reference
+# increases the reference count. See §5.3.5 for more details.
 xx = x
 
 # Setting all references to an immutable object to `None`

examples/03-regions1.frank

@@ -2,16 +2,18 @@
 # The previous examples only worked in the local region drawn in light
 # green. This example shows how new regions can be created and used.
 #
-# The `Region()` constructor creates a new region and returns the bridge
+# The `Region()` constructor creates a new region and returns its bridge
 # object. The new region is drawn in yellow. Any object in the yellow
-# rectangle belongs to the region. The trapezoid shape identifies the
+# rectangle belongs to the region. The trapezoid shape denotes the
 # bridge object. It displays the following information about the region:
-# - LRC:  The number of incomming references from the local region.
-# - SBRC: The number of open subregion.
+# - LRC:  The number of incoming references from the local region. This
+#         counter tracks references to all objects in the region not
+#         just the bridge object. See §3.1 for more details.
+# - SBRC: The number of open subregions.
 # - RC:   The reference count of the bridge object.
 r = Region()
 
-# Any objects assigned to the bridge object or an object in the region
+# Any objects reachable from the bridge or an object in the region
 # will automatically be part of the region. Notice how the new dictionaries
 # are members of the region, indicated by them being in the same yellow box.
 r.field = {}
@@ -22,23 +24,24 @@ r.field.data = {}
 r.field.bridge = r
 r.field.data.parent = r.field
 
-# All objects are by default created in the local region.
+# All objects are by created in the local region.
 x = {}
 x.data = {}
 
-# When a region references an object in the local region, it takes ownership of the
-# object. All referenced objects are also moved into the region. Figure 7 in the paper
-# shows the individual steps of this process.
+# An object in the local region is moved into a region, when an object in the
+# region references it. All reachable objects from the moved object are also
+# moved into the region. Figure 7 in the paper shows the individual steps of
+# this process.
 r.x = x
 
-# Moving the value of `x` into the region increased the LRC since the variable x
-# is a reference from the local frame into the region. Setting x to `None` will
-# decrement the LRC again.
+# Moving the value of `x` into the region increased the LRC since the variable `x`
+# is a reference from the local frame into the region. Reassigning `x` to another
+# value will decrement the LRC again. This is done by a write barrier, discussed in
+# §3.2 of the paper.
 x = None
 
-# References from within a region are allowed to reference frozen objects. This
-# is safe since frozen objects don't have an owner and can be safely shared across
-# threads.
+# References to frozen objects are unrestricted. Table 1 in the paper provides a
+# good overview of what references are allowed.
 r.x.data = None
 
 # When a region has no incoming references it and all contained objects can

examples/04-regions2.frank

@@ -1,28 +1,33 @@
-# The previous example covers how new regions can be created. This
+# 03-regions1.frank covered how new regions can be created. This
 # example covers how ownership is enforced with regions.
 r1 = Region()
 r1.data = {}
 r2 = Region()
 
-# Region 1 owns a dictionary with the name `data`. All objects can at most have
-# one owner. Created a reference from one region to an object in another region
+# Region 1 owns an object with the name `data`. All objects can at most have
+# one owner. Creating a reference from one region to an object in another region
 # will result in an error
 # r2.data = r1.data # Error
 
-# However, it is allowed to create a single reference to a bridge object of
-# another region. This reference is called the owning reference, indicated by
+# However, creating a single reference to a bridge object of another region
+# is allowed. This reference is called the owning reference, indicated by
 # the solid orange arrow. The region of the referenced bridge object is now
 # a subregion of the first region.
 r1.data.r2 = r2
 
 # Attempts to add additional owning references will result in an error:
 # r1.new = r2 # Error
 
+# Regions are arranged in a forest. It is not allowed to create a cycle
+# between regions. Attempting to make `r1` a subregion of `r2` which is
+# currently a subregion of `r1` will result in an error:
+# r2.r1 = r1 # Error
+
 # Region 2 is currently considered open as it has an incoming reference from
 # the local region. This is indicated by the LRC not being zero. The parent
-# region r1 has a SBRC of 1 indicating that a subregion of it is open.
+# region `r1` has a SBRC of 1 indicating that a subregion of it is open.
 #
-# Removing the local reference into r2 will close the region and also decrement
+# Removing the local reference into `r2` will close the region and also decrement
 # the SBRC of the parent region.
 r2 = None
 
@@ -33,15 +38,15 @@ r2 = r1.data.r2
 # This is possible since there can only be one owing reference at a time.
 r1.data.r2 = None
 
-# Region 2 can now take ownership of r1
+# Region 2 can now take ownership of `r1`.
 r2.r1 = r1
 
 # Regions can also be frozen to allow multiple regions to reference them.
 # The bridge object of the frozen region will remain, but it will lose the
 # `[RegionObject]` prototype.
 freeze(r1)
 
-# The previous bridge object referenced by r1 can now be referenced by other
+# The previous bridge object referenced by `r1` can now be referenced by other
 # regions.
 r3 = Region()
 r3.r1 = r1

examples/05-regions3.frank

@@ -1,3 +1,4 @@
+# 04-regions2.frank covered how ownership is enfored with regions.
 # This example covers some built-in functions for regions.
 
 r1 = Region()
@@ -28,6 +29,9 @@ merge(r2.child, r2)
 
 # Regions can also be dissolved, thereby moving all contained
 # objects back into the local region.
+#
+# This function differs syntactically from the paper which
+# uses `merge(r2)`.
 dissolve(r2)
 
 # This can be used to reconstruct regions. This example uses

examples/06-cowns.frank

@@ -1,12 +1,16 @@
+# This is the sixth example and assumes the knowledge of the
+# previous examples.
+#
 # Lungfish uses concurrent owners, called Cowns, to coordinate
-# concurrent access at runtime.
+# concurrent access at runtime. Cowns and their states are
+# introduced in §2.3.1 of the paper.
 #
 # Cowns can store immutable objects, regions and other cowns.
-# The following will create a cown pointing to the frozen value
-# `None`.
+# The following will create a cown pointing to the built-in
+# frozen value `None`.
 c1 = Cown(None)
 
-# The cown has the status "Release" which means that a concurrent
+# The cown has the status "Released" which means that a concurrent
 # unit can aquire it and access its data. Attempting to access
 # the data in this state will result in an error.
 # ref = c1.value # Error
@@ -17,15 +21,15 @@ r1 = Region()
 r1.data = {}
 data = r1.data
 
-# A cown created from an open region has the status "Pending". This
-# status allows access to the contained value. However, it will switch
-# to the "Released" status one the region is closed
+# A cown created from an open region has the status "Pending Release".
+# This status allows access to the contained value. However, it will
+# switch to the "Released" status when the region is closed
 c2 = Cown(r1)
 close(c2.value)
 
-# Cowns can be safely shared across threads since they enfore ownership
-# and concurrent coordination at runtime. They are therefore allowed to
-# be referenced by frozen objects. The freeze will not effect the cown
+# Cowns can be safely shared across threads since they dynamically enforce
+# ownership and concurrent coordination at runtime. They are therefore allowed
+# to be referenced by frozen objects. The freeze will not effect the cown
 # or the contained values.
 x = {}
 x.cown = c2
@@ -44,6 +48,6 @@ r3.cown = c2
 c3 = Cown(move r2)
 
 # Cowns can also point to other cowns. The second cown is also
-# in the *Released* state since the given cown is allowed to
+# in the "Released" state since the given cown is allowed to
 # have local references.
 c4 = Cown(c2)