Version 0.80
- 1. About LuaExec
- 1.1. Overview
- 1.2. What it does and doesn't
- 1.3. Implementation details
- 1.4. Status, outlook
- 1.5. License
- 1.6. Authors, links and downloads
- 2. Installation
- 2.1. Requirements
- 2.2. Adjusting the build environment
- 2.3. Building
- 2.4. Installation
- 2.5. Documentation system
- 3. Examples
- 3.1 Tests
- 3.2 HTTP server
LuaExec is yet another take on multitasking for Lua.
LuaExec is mainly focused on portability and concise semantics. It provides multiple contexts of execution in the most abstract sense, behaving understandably, platform-independent and unencumbered by Lua versions and OS specific details.
- one Lua interpreter per task
- data exchange using messages, signals, arguments and return values
- allows to synchonize on: task completion, signals, messages
- signals: a, t, c, m (abort, terminate, child, message)
- no shared data, no marshalling, this is at the user's discretion
- no operating system details (e.g. priorities)
- LuaExec is a regular module using only the legal Lua API.
- should work with Lua 5.1, 5.2, 5.3, and LuaJIT on POSIX and Windows, if Lua 5.2 and 5.3 are compiled with
LUA_COMPAT_MODULE
, but not all combinations are fully tested.- child tasks are subject to garbage collection in their parent that created them. Their underlying OS threads are always joined and never killed forcibly, and all resources requsted in any task are meant to be returned, at the latest through garbage collection.
- a Lua error in a task raises a signal, a (abort), that is by default propagated to the parent task.
- child tasks and tasks that spawned children are, by default, supplied with a debug hook that checks for the abortion signal, where it raises an error, signals its parent, and so forth.
- the hook can be disabled on a per-task basis. In such tasks abortion strikes only when they are suspended in wait, sleep etc.
This project is a prototype and request for comments. Additions, suggestions, improvements, bug fixes are likely needed and welcome. Performance was no consideration yet. In its current stage it is about getting semantics right.
This project is a spin-off from the tekUI project. The LuaExec 0.80 module is fully contained in (but usable independently of) tekUI version 1.11. The reason for outsourcing was to have a separate testbed and package that is unencumbered by the requirements and complexity of graphical input and output. There are a few examples in this package that can be run against tekUI, and there are a few more tasks examples in the tekUI package.
Given sufficient interest, this library might be extended in a way that other Lua libraries can be written against LuaExec's C and Lua APIs, so that future Lua sockets, I/O, tasks, message libraries and applications can converge and be synchronized on atomically in a platform-independent, Lua-ish way.
LuaExec is free software under the same license as Lua itself: It can be used for both academic and commercial purposes at no cost. It qualifies as Open Source software, and its license is compatible with the GPL – see copyright. Additional components are available under a commercial license – see below.
Authors:
- Timm S. Müller <tmueller at schulze-mueller.de>
Open source project website:
Releases:
Online source code repository:
Development tools and libraries:
- Lua 5.1, 5.2, 5.3, LuaJIT 2.x
- GCC or LLVM/clang
- MinGW (for building for the Windows platform)
Lua 5.2 and 5.3 must be compiled with LUA_COMPAT_MODULE
.
LuaExec does not strictly depend on any external Lua modules. The following modules are supported:
- LuaFileSystem for the HTTP server example and documentation generator
- LuaSocket for the HTTP server example
If building fails for you, you may have to adjust the build
environment, which is located in the config
file on the topmost
directory level. Supported build tools are gmake
(common under
Linux) and pmake
(common under FreeBSD). More build options and
peculiarities are documented in the tekUI package, many of which
apply to the LuaExec package as well.
On FreeBSD and NetBSD you need a Lua binary which is linked with the
-pthread
option, as LuaExec is using multithreaded code in shared
libraries, which are dynamically loaded by the interpreter. For
linking on NetBSD uncomment the respective section in the config
file.
To see all build targets, type
# make help
The regular build procedure is invoked with
# make all
A system-wide installation of LuaExec is not strictly required. Once it is built, it can be worked with and developed against, as long as you stay in the top-level directory of the distribution; all required modules will be found if programs are started from there.
If staying in the top-level directory is not desirable, then LuaExec must be installed globally. By default, the installation paths are
/usr/local/lib/lua/5.1
/usr/local/share/lua/5.1
It is not unlikely that this is different from what is common for
your operating system, distribution or development needs, so be sure
to adjust these paths in the config
file. The installation is
conveniently invoked with
# sudo make install
LuaExec comes with a documentation generator. It is capable of generating a function reference and hierarchical class index from specially crafted comments in the source code. To regenerate the full documentation, invoke
# make docs
Note that you need LuaFileSystem for the document generator to process the file system hierarchy.
Tests are under bin/task/
.
As an example, a small HTTP server (supporting CGI and Lua pages) is included that can be run in the background like this:
local exec = require "tek.lib.exec" local httpd = exec.run(function() require "tek.class.httpd":new { Listen = arg[1], DocumentRoot = "doc" }:run() end, arg[1] or "localhost:8080") -- ... do something else ... httpd:terminate() -- or httpd:join()
To start it serving its own documentation (default localhost:8080):
$ bin/webserver.lua [host:port]
It requires luasocket and lfs, and it supports copas/coxpcall if available. Please note that the HTTP/1.1 part of the webserver is just a hack to have a funny example to work with. It was more written against a browser than against the specification.
Additions, fixes, improvements are welcome.
These links should work when you have loaded this document from the provided HTTP server:
- CGI test page: /webserver/testcgi.lua
- Formtest Lua page: /webserver/formtest.lhtml
- Webserver control Lua page: /webserver/control.lhtml