Provide a way to free the continuation stacks.

* share/txr/stdlib/yield.tl (sys:obtain-impl): Pass
sys:cont-free symbol to each abandoned continuation
to release its stack buffer.
(obtain): Handle the sys:cont-free symbol in the
lambda, so the initial lambda can be treated
uniformly with continuation functions.

* txr.1: Documented sys:obtain-impl.

* unwind.c (sys_cont_free_s): New symbol variable.
(cont_mark): Check for null stack pointer and avoid marking.
(revive_cont): If arg is sys:cont-free, then free the
continuation and return nil. If the continuation has a null
stack buffer, throw an error.
(uw_late_init): Initialize sys_cont_free_s.

1 files changed, 11 insertions, 1 deletions

diff --git a/txr.1 b/txr.1
index cb239c93..975983aa 100644
--- a/txr.1
+++ b/txr.1
@@ -27518,7 +27518,17 @@ is passed to the continuation function, the continuation will be
 resumed in a different manner: its context will be restored as in the
 ordinary resume case, whereupon it will be immediately abandoned by
 a nonlocal exit, causing unwinding to take place across all of the
-evaluation's continuation frames.
+evaluation's continuation frames. The function then returns
+.codn nil .
+
+If the symbol
+.code sys:cont-free
+is passed to the continuation function, the continuation isn't
+be resumed at all; rather, the buffer which holds the saved context
+of the continuation is released. Thereafter, an attempt to resume
+the continuation results in an error exception being thrown.
+After releasing the buffer, the function returns
+.code nil .
 
 .TP* Note: