LuaExec

Version 0.80


Table of contents

Reference


1. About LuaExec

1.1 Overview

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.

1.2 What it does and doesn't

1.3 Implementation details

1.4. Status, outlook

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.

1.5. License

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.

1.6. Authors, links and downloads

Authors:

Open source project website:

Releases:

Online source code repository:


2. Building and installing

2.1. Requirements

Development tools and libraries:

Lua 5.2 and 5.3 must be compiled with LUA_COMPAT_MODULE.

External Lua modules

LuaExec does not strictly depend on any external Lua modules. The following modules are supported:

2.2. Adjusting the build environment

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.

BSD notes

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.

2.3. Building

To see all build targets, type

# make help

The regular build procedure is invoked with

# make all

2.4. Installation

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

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

2.5 Documentation system

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.


3. Examples

3.1 Tests

Tests are under bin/task/.

3.2 HTTP Server example

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.

HTTP server test pages

These links should work when you have loaded this document from the provided HTTP server: