lunatik.runnerModule

Manages the execution and lifecycle of Lunatik scripts.

This module provides functionalities to run scripts as isolated runtimes, spawn them into separate kernel threads, and manage their state (start, stop, list, shutdown). It uses RCU-safe tables to store references to active runtimes and threads. In following descriptions, ‘env’ variable stands for ‘lunatik._ENV’.

Functions

list ()	Lists the names of all currently running scripts.
run (script[, context="process"])	Runs a script in a new runtime of the given context and registers it under its name.
shutdown ()	Shuts down all running scripts and their threads.
spawn (script[, context="process"])	Spawns a Lunatik script in a new kernel thread.
startup ()	Initializes the runner’s internal state.
stop (script)	Stops a running script and its associated thread, if any.

Functions in detail

list ()

Lists the names of all currently running scripts. Iterates over the env.runtimes RCU table to collect script names.

Returns

table

run (script[, context="process"])

Runs a script in a new runtime of the given context and registers it under its name. The runtime runs until runner.stop, which a sentinel ties to the close of the runtime that calls run: see lunatik.runtime.

Parameters

script string path or name of the Lua script to run. The “.lua” extension will be trimmed.
context string or table
execution context, as in lunatik.runtime: "process", "softirq" (netfilter, XDP) or "hardirq" (kprobes); or a table of options:
- context: the execution context, as above.
- percpu: when true, create one runtime per CPU id, dispatched by the CPU a callback fires on; the script runs once per runtime and can read its id with lunatik.cpu(). The runtimes share a netfilter hook and a kprobe; constructors whose registration is global refuse to run in a percpu runtime. A runtime is not a connection: which one a packet reaches is the CPU the hook runs on, so the packets of one flow reach several runtimes. Per-flow state belongs in something the runtimes share, per-CPU state in the runtime.
(default "process")

Returns

runtime or percpu

percpu

Raises

"<script> is already running", "invalid option '<context>'", or the error the script raises on load.

Usage

runner.run("mydriver", "softirq")
runner.run("myfilter", {context = "softirq", percpu = true})

shutdown ()

Shuts down all running scripts and their threads. Stops each script as the iteration reaches it: runner.stop removes the entry the callback was given, which is all rcu.foreach allows.

spawn (script[, context="process"])

Spawns a Lunatik script in a new kernel thread. First, it runs the script using runner.run, then creates a new kernel thread to execute the runtime. The thread is named after the last two components of the script’s path, echod/daemon for examples/echod/daemon. The spawned script is expected to return a function, which will then be executed in the new thread.

Parameters

script string path or name of the Lua script to spawn. The “.lua” extension will be trimmed.
context string execution context of the runtime; only "process" can spawn: a softirq or hardirq runtime raises IRQ runtime cannot spawn threads. (default "process")

Returns

thread

Raises

error if the script is already running, context is not the name of a context, or the thread cannot start, in which case the runtime it created is stopped and unregistered.

startup ()

Initializes the runner’s internal state. Creates the RCU-safe tables for runtimes and threads, reusing the ones a previous startup left in env. A table left by an incompatible runner is rejected: the modules have to be unloaded and loaded.

Raises

error if a table in env is not an rcu table.

stop (script)

Stops a running script and its associated thread, if any. It attempts to stop the thread first, then the runtime.

Parameters

script string name of the script to stop. The “.lua” extension will be trimmed.

Returns

boolean