# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1307314120 -7200
# Node ID e5e090aaacceb3781a1501835d5f53a4ea7bc232
# Parent  e2f7350fba656796e0f710f6b68e595d5de83b07
Added instantiator frame allocation and usage notes.

diff -r e2f7350fba65 -r e5e090aaacce docs/invocation.txt
--- a/docs/invocation.txt	Fri Jun 03 01:33:04 2011 +0200
+++ b/docs/invocation.txt	Mon Jun 06 00:48:40 2011 +0200
@@ -136,6 +136,16 @@
     1   -> argument #3
     2   -> argument #4
 
+  f(obj, 1, 2)    # f known at compile-time
+
+    f   -> C.__new__ (known and called at run-time)
+        -> argument #1 left blank
+    obj -> argument #2
+    1   -> argument #3
+    2   -> argument #4
+
+Frame re-use in instantiators:
+
   Need to call C.__init__(<instance>, obj, 1, 2), preferably with the existing
   frame:
 
@@ -146,6 +156,10 @@
 
   Then jump without switching frames.
 
+  If no context argument (or blank argument) were provided, a new frame would
+  need to be allocated and filled with a new instance and all remaining
+  arguments from the current frame.
+
 Defaults for unknown callables:
 
   f(obj)          # f not known at compile-time
diff -r e2f7350fba65 -r e5e090aaacce rsvplib.py
--- a/rsvplib.py	Fri Jun 03 01:33:04 2011 +0200
+++ b/rsvplib.py	Mon Jun 06 00:48:40 2011 +0200
@@ -380,7 +380,10 @@
         frame = self.local_sp_stack[-1]
 
         # Get the sequence address.
-        # The first argument should be empty.
+        # The first argument should be empty since this function acts as an
+        # instantiator, and in instantiators the first argument is reserved so
+        # that it can be filled in for the call to an initialiser without
+        # allocating a new frame.
 
         obj_value = self.frame_stack[frame + 1]
         return self._builtins_tuple(obj_value)