For the latest stable version, please use Emilua API 0.10!

Emilua

emilua_overview

Emilua is an execution engine. As a runtime for your Lua programs, it’ll orchestrate concurrent systems by providing proper primitives you can build upon.

emilua_simple

Emilua is not a framework. You don’t design the structure of your software by extending a complex concurrency framework. On the contrary, you start simple and only makes use of primitives your application needs. Should you only have the need for simple serial programs, you’ll have access to plenty of IO abstractions that work across a broad range of platforms.

Fibers

emilua_simple

When your software grows and the need to increase the concurrency level a notch arises, just spawn fibers. The same IO abstractions that work on serial programs will work on concurrent programs as well. You don’t need to pay an extra huge cost by completely refactoring your program during this transition[1].

Sandboxes

emilua_simple

Emilua has first-class support for modern sandboxing technologies.

  • Linux namespaces.

  • Linux’s Landlock.

  • FreeBSD’s jails.

  • FreeBSD’s Capsicum.

Mitigate risks by creating disposable cheap sandboxes to parse untrusted input data.

Sandboxing support on Emilua is based around capabilities and elegantly integrates with the same machinery that is used to implement the actor model.

Compartmentalised application development is, of necessity, distributed application development, with software components running in different processes and communicating via message passing.

— Capsicum: practical capabilities for UNIX
Robert N. M. Watson, Jonathan Anderson, Ben Laurie, and Kris Kennaway

The only resource a sandbox starts with is inbox and its only method: receive(). In this initial state, a sandbox can’t even ask for new resources (i.e. it’s a push model). The Lua VM on the host system can then selectively choose which resources are safe to hand over (e.g. read-only access to a file and a pipe).

Cross-platform

  • Windows.

  • Linux.

  • FreeBSD.

Emilua is powered by the battle-tested and scar-accumulating Boost.Asio library to drive IO and it’ll make use of native APIs in a long list of supported platforms. However processor ISA compatibility will be limited by LuaJIT availability.

Network IO

  • TCP.

  • UDP.

  • TLS.

  • Address/service forward/reverse name resolution.

  • IPv6 support (and mostly transparent).

  • Cancellable operations transparently integrated into the fiber interruption API.

  • Several generic algorithms.

IPC

  • UNIX domain sockets (stream, datagram, and seqpacket).

  • SCM_RIGHTS fd-passing.

  • Pipes.

  • UNIX signals.

  • Ctty job control (and basic pty support).

Filesystem API

  • It easily abstracts path manipulation for different platforms (e.g. POSIX & Windows).

  • Transparently translates to UTF-8 while retaining the native representation for the underlying system under the hood.

  • Directory iterators (flat and recursive).

  • APIs to query attributes, manipulate permissions, and the like.

  • Lots of algorithms (e.g. symlink-resolving path canonization, subtrees copying, etc).

  • It focuses on cross-platform support, so not all operations are supported yet, but some platform-specific extensions are already available (e.g. non-Windows umask(3p)).

Misc 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, …​).

  • AWK-inspired scanner to parse textual streams easily.

  • Clocks & timers.

  • File IO (for proactors only[2], so the main thread never blocks).

  • Serial ports.

  • A basic regex module.

  • Native JSON module.

  • Portable error code comparison.

  • And much more.

1. Emilua doesn’t suffer from Bob Nystrom' two colors problem.
2. Right now, Windows' IOCP, and Linux’s io_uring.