Documentation is available online at http://lualanes.github.io/lanes/ (should be the same as what is in the docs folder of the distribution).

===================== Usage on Windows:

For once, Win32 thread prioritazion scheme is actually a good one, and it works. :) Windows users, feel yourself as VIP citizens!!

Windows / MSYS:

On MSYS, 'stderr' output seems to be buffered. You might want to make it auto-flush, to help you track & debug your scripts. Like this:

io.stderr:setvbuf "no"

Even after this, MSYS insists on linewise buffering; it will flush at each newline only.

=================== Usage on Linux:

Linux NTPL 2.5 (Ubuntu 7.04) was used in the testing of Lua Lanes.

This document (http://www.icir.org/gregor/tools/pthread-scheduling.html) describes fairly well, what (all) is wrong with Linux threading, even today.

For other worthy links: http://kerneltrap.org/node/6080 http://en.wikipedia.org/wiki/Native_POSIX_Thread_Library

In short, you cannot use thread prioritation in Linux. Unless you run as root, and I truly would not recommend that. Lobby for yet-another thread implementation for Linux, and mail -> [email protected] about it. :)

CAVEAT: Anyone sufficiently knowledgeable with pthread scheduling is free to contact me bnt DOT germain AT gmail DOT com) with a suitable edit if this no longer applies on more recent kernels.

====================== Usage on Mac OS X:

No real problems in OS X, once everything is set up right...

In short, have your Lua core compiled with LUA_USE_DLOPEN and LUA_USE_POSIX instead of the (default as of 5.1) LUA_DL_DYLD and LUA_USE_MACOSX. This is crucial to have each module loaded only once (even if initialized separately for each thread) and for the static & global variables within the modules to actually be process-wide. Lua Lanes cannot live without... Lua 5.2 is fine in that regard (check luaconf.h to be safe).

Another issue is making sure you only have one Lua core. Your 'lua' binary must link dynamically to a .dylib, it must not carry a personal copy of Lua core with itself. If it does, you will gain many mysterious malloc errors when entering multithreading realm.

<< lua-xcode2(9473,0xa000ed88) malloc: *** Deallocation of a pointer not malloced: 0xe9fc0; This could be a double free(), or free() called with the middle of an allocated block; Try setting environment variable MallocHelp to see tools to help debug <<

rm lua.o luac.o gcc -dynamiclib -install_name /usr/local/lib/liblua.5.1.dylib
-compatibility_version 5.1 -current_version 5.1.2
-o liblua.5.1.2.dylib *.o

gcc -fno-common -DLUA_USE_POSIX -DLUA_USE_DLOPEN -DLUA_USE_READLINE -lreadline -L. -llua.5.1.2 lua.c -o lua

That should be it. :)

Fink 'lua51' packaging has the necessary changes since 5.1.2-3.

===================== Usage on FreeBSD:

Unlike in Linux, also the Lua engine used with Lanes needs to be compiled with '-lpthread'. Otherwise, the following malloc errors are received:

<<
lua in free(): warning: recursive call
PANIC: unprotected error in call to Lua API (not enough memory)
<<

Here are the Lua compilation steps that proved to work (FreeBSD 6.2 i386):

gmake freebsd
rm lua.o luac.o liblua.a
gcc -shared -lm -Wl,-E -o liblua.5.1.2.so *.o
gcc -O2 -Wall -DLUA_USE_LINUX -lm -Wl,-E -lpthread -lreadline -L. -llua.5.1.2 lua.c -o lua

To compile Lanes, use 'gmake' or simply:

cc -O2 -Wall -llua.5.1.2 -lpthread -shared -o out/bsd-x86/lua51-lanes.so \
    -DGLUA_LUA51 gluax.c lanes.c

To place Lua into ~/local, set the following environment variables (this is just a reminder for myself...):

export CPATH=.../local/include
export LIBRARY_PATH=.../local/lib
export LD_LIBRARY_PATH=.../local/lib

======================= Manual installation

After running GNU make, in directory src you will find files lanes.lua and lanes/core.so. The first goes into a directory on your LUA_PATH, and the lanes directory goes into a directory on your LUA_CPATH. If you are not sure how this works, try creating

/usr/local/share/lua/5.1/lanes.lua /usr/local/lib/lua/5.1/lanes/core.so

======================= Note about LuaJIT

It looks like LuaJIT makes some assumptions about the usage of its allocator. Namely, when a Lua state closes, memory allocated from its alloc function might be freed, even if said memory isn't actually owned by the state (for example if the allocator was used explicitly after retrieving if with lua_getallocf) Therefore it seems to be a bad idea, when creating a new lua_State, to propagate the allocator from another state, as closing the first state would invalidate all the memory used by the second one... The best is therefore to leave the 'allocator' configuration option unset when running LuaJIT.

(end)