LEV -- Async I/O Runtime

Timeout semantics

A timeout is an overall deadline for the whole operation: multi-step operations (send, recv_exactly, recv_until, read_all, the TLS handshake) compute deadline = now + timeout once and give each internal wait only the remaining time. A peer trickling one byte per almost-timeout cannot keep an operation alive past its deadline. timeout = nil means no time limit.

One waiter per fd

Only one coroutine may be blocked on a given file descriptor at a time (a second wait_readable/wait_writable on the same fd raises an error). In particular, do not call accept() on one listener from multiple coroutines concurrently.

Closing a socket while another coroutine is blocked on it is safe: the blocked operation returns nil, "closed".

Options

lev.own(resource)

Register a resource (any table with a close() method) for auto-close. Returns the resource for chaining.

lev.spawn(function()
    local sock = lev.own(lev.connect("1.1.1.1", 53, { timeout = 5 }))
    -- sock:close() called automatically when this coroutine exits,
    -- even if an error is thrown
    local data = sock:recv(4096, 5)
end, { detached = true })

lev.defer(fn)

Register an arbitrary cleanup function, like Go's defer.

lev.spawn(function()
    local counter = get_counter()
    counter:increment()
    lev.defer(function() counter:decrement() end)
    -- counter:decrement() runs when this coroutine exits
    do_work()
end)

lev.disown(resource)

Remove a resource from the current task's cleanup list (identity comparison). Use for ownership transfer between coroutines. Returns the resource.

lev.spawn(function()
    local sock = lev.own(lev.connect("1.1.1.1", 53))
    -- Transfer ownership to another task
    lev.disown(sock)
    lev.spawn(function()
        lev.own(sock)
        -- sock is now cleaned up when THIS task exits
    end)
end)

Properties

• Cleanups run on both success and error paths

• LIFO order (last registered runs first)

• Each cleanup is wrapped in pcall -- errors are logged to stderr and don't prevent other cleanups from running

• cleanups list is lazy-initialized (no cost for tasks that don't use it)

• No-op outside lev.run() or from non-spawned coroutines

• Double-close safe (all LEV close methods are idempotent)

lev.sleep(seconds, cancel)

Yields the current coroutine for the given duration (fractional seconds supported). Returns true on normal completion, or nil, "cancelled" if a cancel token fires before the timer expires.

lev.sleep(0.5)  -- sleep 500ms

-- Cancellable sleep
lev.sleep(5.0, token)  -- returns nil, "cancelled" if token fires

lev.now()

Returns the current time from CLOCK_MONOTONIC as a float (seconds with sub-millisecond precision). Available outside lev.run().

local start = lev.now()
do_work()
local elapsed = lev.now() - start

Methods

recvfrom options

The second argument to recvfrom can be a number (timeout in seconds) or a table:

-- Simple timeout
local data, addr, port = sock:recvfrom(4096, 5.0)

-- Table form with cancel token
local data, addr, port = sock:recvfrom(4096, {
    timeout = 5.0,
    cancel = token,
})

lev.tcp()

Creates a raw non-blocking TCP socket. Typically used indirectly via lev.connect() or lev.listen().

lev.connect(addr, port, opts)

High-level connect: creates a TCP socket, performs non-blocking connect (with async wait for EINPROGRESS), and optionally upgrades to TLS.

lev.run(function()
    -- Plain TCP
    local sock, err = lev.connect("1.1.1.1", 53, { timeout = 5 })

    -- TCP + TLS
    local tls_sock, err = lev.connect("1.1.1.1", 853, {
        timeout = 5,
        tls = {
            mode = "client",
            server_name = "cloudflare-dns.com",
            verify = false,
        },
    })
end)

lev.listen(addr, port, opts)

Creates a bound listening TCP socket. Returns a listener object with an accept method that yields until a client connects.

lev.run(function()
    local listener = lev.listen("0.0.0.0", 8080, { reuseport = true })

    while true do
        local client, addr, port = listener:accept(5.0)
        if client then
            lev.spawn(function()
                local data = client:recv(4096, 10)
                client:send("HTTP/1.0 200 OK\r\n\r\nHello")
                client:close()
            end, { detached = true })
        end
    end
end)

TCP socket methods

TCP socket options

lev.connect_unix(path, opts)

Creates an AF_UNIX stream socket and connects to path. Returns a wrapped socket on success.

lev.run(function()
    local sock, err = lev.connect_unix("/run/myservice.sock", { timeout = 5 })
    sock:send("ping")
    local reply = sock:recv(4096, 5)
    sock:close()
end)

lev.listen_unix(path, opts)

Creates a bound AF_UNIX stream listener at path. Returns a listener object with an accept method that yields until a client connects. Because a connecting unix client is typically unbound, accept returns only the wrapped client socket (no peer address/port).

lev.run(function()
    local listener = lev.listen_unix("/run/myservice.sock")
    while true do
        local client = listener:accept(5.0)
        if client then
            lev.spawn(function()
                local data = client:recv(4096, 10)
                client:send("ok")
                client:close()
            end, { detached = true })
        end
    end
end)

Client TLS

local sock = lev.connect("example.com", 443, {
    timeout = 5,
    tls = {
        mode = "client",
        server_name = "example.com",  -- SNI
        verify = true,                -- certificate verification (default)
        cafile = "/etc/ssl/certs/ca-certificates.crt",
    },
})

Server TLS

local listener = lev.listen("0.0.0.0", 443)
local client = listener:accept(5)
client:starttls({
    mode = "server",
    cert = "/path/to/cert.pem",
    key = "/path/to/key.pem",
    verify = false,  -- don't require client certs (default for server)
})

TLS config fields

Server-side SNI

When running a TLS server that serves multiple domains, the hosts field in the starttls config provides per-hostname cert/key pairs. During the TLS handshake, the SNI callback selects the correct certificate based on the client's requested hostname.

client:starttls({
    mode = "server",
    cert = "/default/cert.pem",
    key  = "/default/key.pem",
    hosts = {
        ["example.com"]    = { cert = "/certs/example.com.crt",   key = "/keys/example.com.key" },
        ["*.example.org"]  = { cert = "/certs/_.example.org.crt", key = "/keys/_.example.org.key" },
    },
})

Matching order:

1. Exact match: hostname matches a key exactly

2. Wildcard match: *.domain matches any single-label prefix (e.g. *.example.org matches api.example.org but not deep.sub.example.org)

3. Default: if no match, the default cert/key is used

Each entry in the hosts table must have both cert and key paths pointing to valid PEM files. Invalid entries cause starttls to fail instead of being silently ignored.

TLS-aware error strings

In addition to the standard error protocol, TLS operations may return:

Token fields

lev.race(fns)

Spawns each function concurrently. Returns the first result (success or error) and cancels the remaining tasks. Each function receives a cancel token as its first argument.

local result = lev.race({
    function(token)
        lev.sleep(0.1)
        return "fast"
    end,
    function(token)
        lev.sleep(10.0)
        return "slow"
    end,
})
-- result == "fast"

lev.all(fns)

Spawns each function and waits for all to complete. Returns a list of result tables. If any task errors, cancels the rest and returns nil, err immediately.

local results, err = lev.all({
    function(token) return "a" end,
    function(token) return "b" end,
})
-- results == { {"a"}, {"b"} }

-- Fail-fast on error
local results, err = lev.all({
    function(token) error("boom") end,
    function(token) lev.sleep(10) end,
})
-- results == nil, err matches "boom"

Stopping the loop

lev.stop() sets the loop's running flag to false, causing lev.run() to exit on the next iteration regardless of active coroutines. This is intended for signal handlers that need to enforce a shutdown deadline:

lev.run(function()
    lev.on_signal(lev.SIGTERM, function()
        shutdown = true
        lev.spawn(function()
            lev.sleep(5)   -- grace period for in-flight work
            lev.stop()     -- force exit
        end, { detached = true })
    end)

    while not shutdown do
        -- serve requests
    end
end)

Signal constants

TCP userdata methods (C level)

Options

Process methods

All methods accepting timeout_or_opts support: a number (timeout in seconds), or a table { timeout = N, cancel = token }.

Exec failure detection

If execvp/execve fails (e.g. command not found), lev.exec() returns nil, err immediately. This uses the self-pipe trick: a CLOEXEC pipe that the child writes errno to on exec failure; the parent reads it before returning the userdata.

Bidirectional I/O

For commands that both read stdin and produce output, use separate coroutines to prevent deadlocks:

lev.run(function()
    local proc = lev.exec("/bin/cat")
    local writer = lev.spawn(function()
        proc:send(big_data)
        proc:close_stdin()
    end)
    local reader = lev.spawn(function()
        return proc:read_all(10)
    end)
    lev.await(writer)
    local output = lev.await(reader)
    proc:wait(5)
    proc:close()
end)

Signal constants

(In addition to the existing SIGTERM, SIGINT, SIGHUP, SIGUSR1, SIGUSR2.)

Subprocess C core API

lev.set_nonblocking(fd, enable)

Sets or clears O_NONBLOCK on an arbitrary fd. Returns the previous non-blocking state (boolean) so callers can restore it, or nil, err. Required before cooperatively reading a shared fd (e.g. stdin) through the event loop. Available outside lev.run().

lev.fd_reader(fd)

Wraps an arbitrary fd (e.g. stdin) for cooperative reads on the event loop. The fd must be in non-blocking mode (see set_nonblocking) and must be epoll-able (a TTY or pipe, not a regular file).

lev.run(function()
    local was_nb = lev.set_nonblocking(0, true)
    local reader = lev.fd_reader(0)
    local bytes, err = reader:read(512, 5.0)  -- yields until input or timeout
    reader:close()
    lev.set_nonblocking(0, was_nb)
end)

lev.set_logger(logger)

Injects a std.logger instance for structured error reporting. When set, cleanup errors and detached task errors are routed through the logger instead of raw io.stderr:write(). The logger persists across run() calls. Pass nil to revert to stderr.

local std = require("std")
local logger = std.logger.new("info")
lev.set_logger(logger)

lev.task_name(name)

Sets and/or returns the current task's name. With an argument, sets the name and returns it. Without an argument, returns the current name (or nil). No-op outside lev.run().

lev.spawn(function()
    lev.task_name("request-handler")
    -- ...
end)

Tasks can also be named at spawn time via opts.name. The main task is automatically named "main".

lev.stats()

Returns a table with fast loop counters. Returns nil outside lev.run().

lev.run(function()
    local s = lev.stats()
    print(s.active_coros, s.task_count)
end)

lev.task_tree()

Returns a sorted array of task info tables. Returns nil outside lev.run().

Each entry has: id, name, status, detached, parent_id, co_status. Sorted by id for stable output. co_status is from coroutine.status().

lev.run(function()
    lev.spawn(function() lev.sleep(1) end, { name = "worker" })
    for _, t in ipairs(lev.task_tree()) do
        print(t.id, t.name, t.status, t.co_status)
    end
end)

lev.task_dump()

Like task_tree() but adds a traceback field for suspended coroutines, showing the exact yield point (e.g. sleep → timer_sleep). Has meaningful overhead -- use for debugging, not monitoring.

lev.enable_dump_signal(format)

Registers a SIGUSR1 handler that calls task_dump() and outputs the result. Supports "text" (default) and "json" formats. Uses the injected logger if set, otherwise stderr. Safe because LEV signal handlers run via signalfd dispatch, not async-signal context.

lev.run(function()
    lev.enable_dump_signal()  -- or "json"
    lev.spawn(function() lev.sleep(30) end, { name = "sleeper" })
    lev.sleep(30)
end)
-- Then: kill -USR1 <pid>

Text output example:

=== LEV task dump ===
  task #1 "main"  status=pending  co=suspended  detached=false  parent=none
  task #2 "sleeper"  status=pending  co=suspended  detached=false  parent=1
=== end dump ===