Emilua

An execution engine^[1] for Lua.

Features:

• Complete fiber API (sync primitives, interruption API, clean-up handlers, fiber local storage, assert-like scheduling constraints, …​).

• Integrates with Lua builtins (i.e. you can mix up fibers and coroutines, modules, …​).

• HTTP^[2].

• Actor API (each VM is an actor and they’re spawned in thread pools under your control^[3]).

• Native JSON module.

• Cross-platform (should run anywhere Boost.Asio also runs).

Hello World

local sleep = require('sleep')

local numbers = {8, 42, 38, 111, 2, 39, 1}

for _, n in pairs(numbers) do
    spawn(function()
        sleep(n / 100)
        print(n)
    end)
end

Actor example

local inbox = require('inbox')

print('actor started with _CONTEXT=' .. _CONTEXT)

if _CONTEXT == 'main' then
    local ch = spawn_vm('.')
    ch:send{ from = inbox, body = 'Hello World' }
    local m = inbox:receive()
    print(m)
else assert(_CONTEXT == 'worker')
    local m = inbox:receive()
    m.from:send(m.body)
end

Dependencies

• Meson 0.55.0 or later.

• C++17 compiler (GCC 10 or newer should work).

• LuaJIT.

• Boost.Asio (and other Boost libraries as well).

• fmt 8.0 or later.

• re2c 1.3 or later.

• xxd.

Optional dependencies

• Curses: coloured output on errors.

• asciidoctor: manpages.

• GNU AWK: tests.

Install

• ArchLinux.

• GUIX: Emilua is available from the main repository.

BUILD

$ mkdir build
$ cd build
$ meson ..
$ ninja

An emilua binary will be generated. Copy it to your $PATH.

You can also pass options when you invoke meson. One of the options is -D enable_http=true.

It’s encouraged that you build luajit with -DLUAJIT_ENABLE_LUA52COMPAT.

LICENSE

• C/C++ source code under Boost Software License.

• Lua code (including snippets scattered through the documentation) distributed in this repo is released as public domain.

• Documentation (except for the source code samples contained within) is licensed under the Creative Commons Attribution 4.0 International License.

• Submodules and dependencies have their own licensing terms.

Documentation

You can browse the documentation online at https://emilua.gitlab.io/docs/.

Alternatively, you may pass -Denable_manpages=true when building the project to have the documentation installed as manpages in your system. The reference pages will be installed in the section 3em ("em" stands for Emilua Module). Tutorial pages will be installed in section 7, but every page in this section will be prefixed by "emilua-".

Tests

$ ninja test

You also need to have GNU AWK installed to run the tests.

Some tests are more intrusive and can only be built if you enable the plugins support.

Some fuzz tests are also available. You can configure the seed for these tests by setting the EMILUA_TEST_SEED environment variable. The envirnoment variable EMILUA_TEST_FUZZER_NITER can be used to override the number of iterations.

ROADMAP

• More plugins.

  • D-Bus plug-in.

  • Python plug-in.

  • Redis plug-in.

• Linux namespaces powered actors when available+requested.

• Self-contained executables.

• REPL.

• Debugger.

• Custom memory allocator per VM.

• Try to infect other languages with similar ideas.

---

1. If you don’t know what is an execution engine think NodeJS.

2. WebSocket planned for next releases.

3. The default profile inherits the parent execution context (no new thread is created), but the option to create a new one is also available.