From bc0fe5c0707bdaa3ae780c3f48b106234c623e1f Mon Sep 17 00:00:00 2001
From: Miguel Sofer <miguel.sofer@gmail.com>
Date: Mon, 23 Mar 2015 02:11:30 +0000
Subject: updated, improved tailcall comments

---
 generic/tclBasic.c | 45 +++++++++++++++++++++------------------------
 1 file changed, 21 insertions(+), 24 deletions(-)

diff --git a/generic/tclBasic.c b/generic/tclBasic.c
index 361ed49..e92e8e9 100644
--- a/generic/tclBasic.c
+++ b/generic/tclBasic.c
@@ -4142,8 +4142,9 @@ TclNREvalObjv(
 
     /*
      * data[1] stores a marker for use by tailcalls; it will be set to 1 by
-     * command redirectors (imports, alias, ensembles) so that tailcalls
-     * finishes the source command and not just the target.
+     * command redirectors (imports, alias, ensembles) so that tailcall skips
+     * this callback (that marks the end of the target command) and goes back
+     * to the end of the source command. 
      */
 
     if (iPtr->deferredCallbacks) {
@@ -4406,7 +4407,7 @@ NRCommand(
     iPtr->numLevels--;
 
      /*
-      * If there is a tailcall, schedule it
+      * If there is a tailcall, schedule it next
       */
  
     if (data[1] && (data[1] != INT2PTR(1))) {
@@ -8170,27 +8171,24 @@ Tcl_NRCmdSwap(
 }
 
 /*****************************************************************************
- * Stuff for tailcalls
+ * Tailcall related code
  *****************************************************************************
  *
- * Just to show that IT CAN BE DONE! The precise semantics are not simple,
- * require more thought. Possibly need a new Tcl return code to do it right?
- * Questions include:
- *   (1) How is the objc/objv tailcall to be run? My current thinking is that
- *	 it should essentially be
- *	     [tailcall a b c] <=> [uplevel 1 [list a b c]]
- *	 with two caveats
- *	     (a) the current frame is dropped first, after running all pending
- *		 cleanup tasks and saving its namespace
- *	     (b) 'a' is looked up in the returning frame's namespace, but the
- *		 command is run in the context to which we are returning
- *	 Current implementation does this if [tailcall] is called from within
- *	 a proc, errors otherwise.
- *   (2) Should a tailcall bypass [catch] in the returning frame? Current
- *	 implementation does not (or does it? Changed, test!) - it causes an
- *	 error.
- *
- * FIXME NRE!
+ * The steps of the tailcall dance are as follows:
+ *
+ *   1. when [tailcall] is invoked, it stores the corresponding callback in
+ *      the current CallFrame and returns TCL_RETURN
+ *   2. when the CallFrame is popped, it calls TclSetTailcall to store the
+ *      callback in the proper NRCommand callback - the spot where the command
+ *      that pushed the CallFrame is completely cleaned up
+ *   3. The NRCommand schedules the tailcall callback to run immediately after
+ *      NRCommand returns
+ *
+ *   One delicate point is to properly define the NRCommand where the tailcall
+ *   will execute. There are functions whose purpose is to help define the
+ *   precise spot: TclMarkTailcall ("this is the spot") and TclSkipTailcall
+ *   ("skip the next command: we are redirecting to it, tailcalls should run
+ *   after WE return"), TclPushTailcallPoint (special for OO).
  */
 
 void
@@ -8282,8 +8280,7 @@ TclNRTailcallObjCmd(
     /*
      * Create the callback to actually evaluate the tailcalled
      * command, then set it in the varFrame so that PopCallFrame can use it
-     * at the proper time. Being lazy: exploit the TclNRAddCallBack macro to
-     * build the callback.
+     * at the proper time.
      */
 
     if (objc > 1) {
-- 
cgit v0.12