New functions 'lua_resetthread' and 'coroutine.kill'

New functions to reset/kill a thread/coroutine, mainly (only?) to
close any pending to-be-closed variable. ('lua_resetthread' also
allows a thread to be reused...)

1 files changed, 30 insertions, 4 deletions

diff --git a/manual/manual.of b/manual/manual.of
index 0e8e3d72..862d032b 100644
--- a/manual/manual.of
+++ b/manual/manual.of
@@ -3927,6 +3927,19 @@ and then pops the top element.
 
 }
 
+@APIEntry{int lua_resetthread (lua_State *L);|
+@apii{0,?,-}
+
+Resets a thread, cleaning its call stack and closing all pending
+to-be-closed variables.
+Returns a status code:
+@Lid{LUA_OK} for no errors in closing methods,
+or an error status otherwise.
+In case of error,
+leave the error object on the stack,
+
+}
+
 @APIEntry{int lua_resume (lua_State *L, lua_State *from, int nargs,
                           int *nresults);|
 @apii{?,?,-}
@@ -3948,11 +3961,8 @@ or returned by the body function.
 @Lid{LUA_OK} if the coroutine finishes its execution
 without errors,
 or an error code in case of errors @seeC{lua_pcall}.
-
 In case of errors,
-the stack is not unwound,
-so you can use the debug API over it.
-The error object is on the top of the stack.
+the error object is on the top of the stack.
 
 To resume a coroutine,
 you remove all results from the last @Lid{lua_yield},
@@ -6285,6 +6295,17 @@ it is not inside a non-yieldable @N{C function}.
 
 }
 
+@LibEntry{coroutine.kill(co)|
+
+Kills coroutine @id{co},
+closing all its pending to-be-closed variables
+and putting the coroutine in a dead state.
+In case of error closing some variable,
+returns @false plus the error object;
+otherwise returns @true.
+
+}
+
 @LibEntry{coroutine.resume (co [, val1, @Cdots])|
 
 Starts or continues the execution of coroutine @id{co}.
@@ -8648,6 +8669,11 @@ has been removed.
 When needed, this metamethod must be explicitly defined.
 }
 
+@item{
+When a coroutine finishes with an error,
+its stack is unwound (to run any pending closing methods).
+}
+
 }
 
 }