Module lunatik.runner

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[, ispercpu]]) Runs a Lunatik script in the current context.
shutdown () Shuts down all running scripts and their threads.
spawn (script) 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

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

Returns:

    string A comma-separated string of running script names, or an empty string if no scripts are running.
run (script[, context[, ispercpu]])
Runs a Lunatik script in the current context. Creates a new Lunatik runtime for the given script and registers it. Throws an error if a script with the same name is already running.

Parameters:

  • script string path or name of the Lua script to run. The ".lua" extension will be trimmed.
  • context string Execution context: "process" (default) or "softirq" (for netfilter/XDP hooks). (optional)
  • ispercpu boolean create one runtime per CPU id, dispatched by the CPU a callback fires on; the script runs once per instance and can read its id with lunatik.cpu(). Netfilter hooks and constructors whose registration is global refuse to run in an instance. (optional)

Returns:

    table created Lunatik runtime object, or the percpu object when ispercpu is set.

Raises:

error if the script is already running.
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.map allows.
spawn (script)
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 based on the script's filename. 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.

Returns:

    userdata kernel thread object.

Raises:

error if the script is already running or percpu is set.
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.
generated by LDoc 1.5.0 Last updated 2026-09-05 12:27:44