Cleaner protocol between 'lua_dump' and writer function

'lua_dump' signals to the writer function the end of a dump, so that
is has more freedom when using the stack.

1 files changed, 19 insertions, 2 deletions

diff --git a/manual/manual.of b/manual/manual.of
index 8607e57d..ef1bdfd2 100644
--- a/manual/manual.of
+++ b/manual/manual.of
@@ -3266,6 +3266,13 @@ As it produces parts of the chunk,
 with the given @id{data}
 to write them.
 
+The function @Lid{lua_dump} fully preserves the Lua stack
+through the calls to the writer function,
+except that it may push some values for internal use
+before the first call,
+and it restores the stack size to its original size
+after the last call.
+
 If @id{strip} is true,
 the binary representation may not include all debug information
 about the function,
@@ -3275,8 +3282,6 @@ The value returned is the error code returned by the last
 call to the writer;
 @N{0 means} no errors.
 
-This function does not pop the Lua function from the stack.
-
 }
 
 @APIEntry{int lua_error (lua_State *L);|
@@ -4688,6 +4693,10 @@ passing along the buffer to be written (@id{p}),
 its size (@id{sz}),
 and the @id{ud} parameter supplied to @Lid{lua_dump}.
 
+After @Lid{lua_dump} writes its last piece,
+it will signal that by calling the writer function one more time,
+with a @id{NULL} buffer (and size 0).
+
 The writer returns an error code:
 @N{0 means} no errors;
 any other value means an error and stops @Lid{lua_dump} from
@@ -9260,6 +9269,14 @@ it is equivalent to @Lid{lua_closethread} with
 }
 
 @item{
+The function @Lid{lua_dump} changed the way it keeps the stack
+through the calls to the writer function.
+(That was not specified in previous versions.)
+Also, it calls the writer function one extra time,
+to signal the end of the dump.
+}
+
+@item{
 There were several changes in the parameters
 for the options @Lid{LUA_GCINC} and @Lid{LUA_GCGEN}
 of the function @Lid{lua_gc}.