>From 0c899e96d9667a88ceb17cfbcdedf3e18aeef21c Mon Sep 17 00:00:00 2001
From: Nala Ginrut <address@hidden>
Date: Thu, 4 Apr 2013 14:14:25 +0800
Subject: [PATCH] Add escape continuation with docs

* ref/api-control.texi: Add docs
* ice-9/control.scm: Add let/ec and call/ec
* ice-9/futures.scm: Remove the old let/ec implementation.
---
 doc/ref/api-control.texi |   23 +++++++++++++++++++++++
 module/ice-9/control.scm |   27 +++++++++++++++++++++++++--
 module/ice-9/futures.scm |   11 +----------
 3 files changed, 49 insertions(+), 12 deletions(-)

diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi
index 320812d..9ddeeb0 100644
--- a/doc/ref/api-control.texi
+++ b/doc/ref/api-control.texi
@@ -577,6 +577,29 @@ Before moving on, we should mention that if the handler of a prompt is a
 that prompt will not cause a continuation to be reified. This can be an
 important efficiency consideration to keep in mind.
 
address@hidden {Scheme Procedure} call/ec proc
+'ec' stands for escape-continuation, or so-called 'one-shot' continuation.
address@hidden/ec} is equivalent to call-with-escape-continuation. 
+A continuation obtained from call/ec is actually a kind of prompt. @var{call/ec}
+is often an easy replacement for @var{call/cc} to improve performance.
+More details read @uref{http://www.cs.indiana.edu/~bruggema/one-shots-abstract.html, 
+Representing control in the presence of one-shot continuations}.
address@hidden deffn
+
address@hidden {Scheme Syntax} let/ec k body
+Equivalent to (call/ec (lambda (k) body ...)).
address@hidden deffn
+
address@hidden
+(use-module (ice-9 control))
+
+(call/ec (lambda (return)
+           (return 123)))
+
+(let/ec return (return 123))
address@hidden example
+
+
 @node Shift and Reset
 @subsubsection Shift, Reset, and All That
 
diff --git a/module/ice-9/control.scm b/module/ice-9/control.scm
index 5f25738..4a114fd 100644
--- a/module/ice-9/control.scm
+++ b/module/ice-9/control.scm
@@ -1,6 +1,6 @@
 ;;; Beyond call/cc
 
-;; Copyright (C) 2010, 2011 Free Software Foundation, Inc.
+;; Copyright (C) 2010, 2011, 2013 Free Software Foundation, Inc.
 
 ;;;; This library is free software; you can redistribute it and/or
 ;;;; modify it under the terms of the GNU Lesser General Public
@@ -21,7 +21,7 @@
 (define-module (ice-9 control)
   #:re-export (call-with-prompt abort-to-prompt
                default-prompt-tag make-prompt-tag)
-  #:export (% abort shift reset shift* reset*))
+  #:export (% abort shift reset shift* reset* call/ec let/ec))
 
 (define (abort . args)
   (apply abort-to-prompt (default-prompt-tag) args))
@@ -76,3 +76,26 @@
 
 (define (shift* fc)
   (shift c (fc c)))
+
+(define %call/ec-prompt
+  (make-prompt-tag))
+
+(define-syntax-rule (call/ec proc)
+  ;; aka. `call-with-escape-continuation'
+  (let ((tag (make-prompt-tag)))
+    (call-with-prompt 
+     tag
+     (lambda ()
+       (proc (lambda args (apply abort-to-prompt args))))
+     (lambda (_ . args)
+       (apply values args)))))
+
+(define-syntax-rule (let/ec k e e* ...)
+  ;; aka. `let-escape-continuation'
+  (let ((tag (make-prompt-tag)))
+    (call-with-prompt
+     tag
+     (lambda ()
+       (let ((k (lambda args (apply abort-to-prompt tag args))))
+         e e* ...))
+     (lambda (_ . results) (apply values results)))))
diff --git a/module/ice-9/futures.scm b/module/ice-9/futures.scm
index 35a36ca..90bbe53 100644
--- a/module/ice-9/futures.scm
+++ b/module/ice-9/futures.scm
@@ -23,6 +23,7 @@
   #:use-module (srfi srfi-11)
   #:use-module (ice-9 q)
   #:use-module (ice-9 match)
+  #:use-module (ice-9 control)
   #:export (future make-future future? touch))
 
 ;;; Author: Ludovic Courtès <address@hidden>
@@ -105,16 +106,6 @@ touched."
       (lambda () (begin e0 e1 ...))
       (lambda () (unlock-mutex x)))))
 
-(define-syntax-rule (let/ec k e e* ...)           ; TODO: move to core
-  (let ((tag (make-prompt-tag)))
-    (call-with-prompt
-     tag
-     (lambda ()
-       (let ((k (lambda args (apply abort-to-prompt tag args))))
-         e e* ...))
-     (lambda (_ res) res))))
-
-
 (define %future-prompt
   ;; The prompt futures abort to when they want to wait for another
   ;; future.
-- 
1.7.10.4