Coco changes the semantics of several standard API functions and provides a few API extensions for Lua.
By default all your coroutines get an associated C stack. If you want to be more selective, see below.
Lua API extensions
All coroutine.* functions should be fully upwards compatible.
This field is true when Coco is present (nil otherwise).
coro = coroutine.create(f [, cstacksize])
func = coroutine.wrap(f [, cstacksize])
The optional argument cstacksize specifies the size of the C stack to allocate for the coroutine:
- A default stack size is used if cstacksize is not given or is nil or zero.
- No C stack is allocated if cstacksize is -1.
- Any other value is rounded up to the minimum size (i.e. use 1 to get the minimum size).
Important notice for LuaJIT: JIT compiled functions cannot yield if a coroutine does not have a dedicated C stack.
olddefault = coroutine.cstacksize([newdefault])
Returns the current default C stack size (may be 0 if the underlying context switch method has its own default). Sets a new default C stack size if newdefault is present. Use 0 to reset it to the default C stack size. Any other value is rounded up to the minimum size.
C API extensions
All C API functions are either unchanged or upwards compatible.
int lua_yield(lua_State *L, int nresults)
The semantics for lua_yield() have changed slightly. Existing programs should work fine as long as they follow the usage conventions from the Lua manual:
return lua_yield(L, nresults);
Previously lua_yield() returned a 'magic' value (-1) that indicated a yield. Your C function had to pass this value on to the Lua core and was not called again.
Now, if the current coroutine has an associated C stack, lua_yield() returns the number of arguments passed back from the resume. This just happens to be the right convention for returning them as a result from a C function. I.e. if you used the above convention, you'll never notice the change.
But the results are on the Lua stack when lua_yield() returns. So the C function can just continue and process them or retry an I/O operation etc. And your whole C stack frame (local variables etc.) is still there, too. You can yield from anywhere in your C program, even several call levels deeper.
Of course all of this only works with Lua+Coco and not with standard Lua.
lua_State *lua_newcthread(lua_State *L, int cstacksize)
This is an (optional) new function that allows you to create a coroutine with an associated C stack directly from the C API. Other than that it works the same as lua_newthread(L).
You have to declare this function as extern yourself, since it's not part of the official Lua API. This means that a C module that uses this call cannot be loaded with standard Lua. This may be intentional.
If you want your C module to work with both standard Lua and Lua+Coco you can check whether Coco is available with:
lua_getfield(L, LUA_GLOBALSINDEX, "coroutine"); lua_getfield(L, -1, "coco"); coco_available = lua_toboolean(L, -1); lua_pop(L, 2);
You can also create coroutines with a C stack by calling the Lua function coroutine.create() from C.