LuaExec

Version 0.80


Table of contents

Reference


1. About LuaExec

1.1 Overview

LuaExec is 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 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 LuaExec is about getting semantics right. Some considerations:

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.

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

Only for the included webserver and documentation generator: 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.

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 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. The server itself is not multithreaded, but 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.

HTTP server test pages

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