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 general applicability, simplicity and concise semantics. It provides multiple contexts of execution in the most abstract sense, behaving understandably, platform-independently and unencumbered by Lua versions and OS specific details.
- runs a Lua interpreter per task
- is recursive: A child task can require the
tek.lib.exec
module again and run child tasks again- data exchange using messages, signals, arguments and return values
- allows to synchronize on: task completion, signals, messages
- abstract signals: a, t, c, m (abort, terminate, child, message)
- tasks can find each other by name or by parent
- 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.
- It 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 requested 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 LuaExec 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 modules and libraries can be written against LuaExec's C and Lua APIs, so that future Lua sockets and I/O, 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:
- 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.
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 LuaExec's 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.
As for the rest of the package, fixes, improvements and suggestions 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