Re: luaL_buffinit stack manipulation

[Andrew Gierth <andrew@...>]

>>>>> "Benoit" == Benoit Germain <bnt.germain@gmail.com> writes:

 Benoit> Hello,
 Benoit> I've just discovered that in Lua 5.4.3, luaL_buffinit pushes a
 Benoit> light userdata on the stack, which it did not do in previous
 Benoit> versions.

In previous versions, the luaL_Buffer functions would push a (full)
userdata, or in older versions possibly multiple full userdatas, onto
the stack at some unpredictable point. Hence the warnings about balanced
stack usage when using luaL_Buffer in the documentation.

This interface has been a _major_ cause of subtle bugs even for
experienced programmers (there are many examples in the list archives),
so there was a desire to at least have a way to check for those bugs.
5.4.3 compiled with asserts enabled will give an assert failure in at
least some cases of misuse; and it may be the ability to check this
assertion that prompted the "push a lightuserdata on the stack
immediately as a placeholder" change (it's part of the same commit).

The placeholder lightuserdata is replaced with a full userdata when the
initial buffer space in the luaL_Buffer is filled.

 Benoit> However, the documentation for the function is [-0, +0, –] ,
 Benoit> meaning we should not expect anything to be pushed on the
 Benoit> stack, nor any error raised. Also, API incompatibility doesn't
 Benoit> say anything about it either.

That may qualify as a documentation bug; [-0, +?, -] would be more
accurate.

-- 
Andrew.