incompatibilities to 5.0 beta

[Roberto Ierusalimschy <roberto@...>]

Soon we will release Lua 5.0 beta. Here is a list of incompatibilities
from 5.0 alpha to 5.0 beta. (Most of them relate to coroutines; this is
an area that is still green in Lua.)

* the API to weak tables is back to the beginning: no more
setmode/getmode; it uses the field "__mode" in the metatable.

* as we have anticipated, there are no more __gettable/__settable
metaindices. They have been unified with __index/__newindex.

* Threads are a new type in Lua. (That was necessary to solve the
problem of garbage-collecting coroutines.) The call

  LUA_API lua_State *lua_newthread (lua_State *L);

leaves the new thread on the stack. All threads but the main one are
garbage collectible. For coroutines, this is just what we need. Other
multi-threaded systems (like LuaThreads) may store threads in the
registry, for instance, to avoid their collection.


* The API for coroutines changed too. "coroutine.create" now returns a
coroutine (an object of type "thread"), and not a function. There is an
explicit "coroutine.resume" to resume a coroutine. We feel that this API
is simpler for most people to understand. The old functionality is still
available as "coroutine.wrap", that creates a coroutine and "wraps" it
inside a function (closure), that resumes the coroutine each time it is
called.

* "coroutine.resume" can pass parameters to yield. "coroutine.create"
(and "coroutine.wrap") now take only one argument, the coroutine body.
The fist time you resume it, the extra arguments to "resume" (or the
arguments to the closure, when you use "wrap") go as the parameters
to the body. Next time you resume again the extra arguments go as
the results from "yield". For instance:

x = coroutine.create(function (a,b,c)
      print(a,b,c)
      print(coroutine.yield())
      print(coroutine.yield())
    end)

coroutine.resume(x, 1, 2, 3)       --> 1, 2, 3
coroutine.resume(x, 10)       --> 10
coroutine.resume(x, 4, 5)	   --> 4, 5
print(coroutine.resume(x))   --> false   cannot resume dead coroutine


* coroutine.resume works in "protected mode", like pcall. Its first
return is true or false (absence or presence of errors). If true, the
other results are the arguments to yield, or the return of the body. If
false, the other argument is the error message. (The function returned
by "wrap" does not work in protected mode.)


* the macro LUA_USERSTATE now opens an extra space *before* the area
pointed by lua_State.

-- Roberto