Coco

Coco is a small extension to get True C Coroutine semantics for Lua 5.1.

Coco is both available as a stand-alone release and integrated into » LuaJIT.

The stand-alone release is a patchset against the » standard Lua 5.1.2 distribution. There are no dependencies on LuaJIT. However LuaJIT depends on Coco to allow yielding for JIT compiled functions.

Features

True C coroutine semantics mean you can yield from a coroutine across a C call boundary and resume back to it.

Coco allows you to use a dedicated C stack for each coroutine. Resuming a coroutine and yielding from a coroutine automatically switches C stacks, too.

In particular you can now:

Yield across all metamethods (not advised for __gc).
Yield across iterator functions (for x in func do).
Yield across callbacks (table.foreach(), dofile(), ...).
Yield across protected callbacks (pcall(), xpcall(), ...).
Yield from C functions and resume back to them.

Best of all, you don't need to change your Lua or C sources and still get the benefits. It's fully integrated into the Lua core, but tries to minimize the required changes.

Installation

Fetch the » Lua 5.1.2 source distribution, unpack it, rename it and cd into it:
  wget http://www.lua.org/ftp/lua-5.1.2.tar.gz
  tar zxf lua-5.1.2.tar.gz
  mv lua-5.1.2 lua-5.1.2-coco
  cd lua-5.1.2-coco
Patch the sources:
patch -p1 <../lua-5.1.2-coco-1.1.3.patch
If you don't have "patch" or don't know how to use it, please read » this Wiki page.
Optionally edit Makefile, src/Makefile or src/luaconf.h. Please check the portability requirements for some caveats.
Run make, supplying your platform as a target. E.g. for Linux:
make linux
Try out some coroutine tests:
  ./src/lua ../cocotest/cotest.lua
  ./src/lua ../cocotest/cocreate.lua
  ./src/lua ../cocotest/comessage.lua
  ./src/lua ../cocotest/chameneos.lua
Optionally install the modified version of Lua:
make install

More ...

Please visit the » Download page to fetch the current version of the stand-alone package.

Coco needs some machine-specific features — please have a look at the Portability Requirements.

Coco also provides some upwards-compatible API Extensions for Lua.