Processes

Run other programs from Lua: read a command’s output, launch an app the user keeps, or hold a long-running program across reloads. Call them from event handlers (on_click, on_change, a timer) or a module’s top level. Storage, timers, actions and the utilities are on scripting; Supervisor, Renderer and push are in the glossary.

A temperature from an HTTP API that refreshes on click, with process.run, json, log and a named state:

local temperature = state("temperature", "--")

local function refresh()
    local body = {}
    process.run("curl", { "-fsS", "--max-time", "5",
        "https://api.open-meteo.com/v1/forecast?latitude=52.52&longitude=13.41&current_weather=true" },
        function(line, stream)
            if stream == "stdout" then body[#body + 1] = line end
        end,
        function(code)
            local data = code == 0 and json.decode(table.concat(body)) or nil
            if type(data) == "table" and data.current_weather then
                temperature:set(string.format("%.0f°", data.current_weather.temperature))
            else
                log.warn("weather: no reading; curl exited with", code)
            end
        end)
end
refresh()

return panel {
    id = "weather", layer = "top", anchor = { top = true },
    child = rect {
        on_click = refresh,
        children = { text { content = temperature, font_size = 14 } },
    },
}

Which one do I use

• Whole stdout as one string and the exit code once it ends: process.capture.
• Lines as they arrive, or a stream that never ends (tail -f): process.run. A long-running one restarts with each save.
• One instance that must outlive a save or a crash: session_process.
• A program the user keeps after the shell: process.detach.

What else survives a reload, a crash and a stop: runtime.

process.run

Spawns a helper, streams its output line by line, and reports its exit.

The call returns immediately. A spawn failure (command not on PATH) reaches Lua only as on_exit(nil) with no output; the reason is logged as a warning.

process.capture

Runs a helper to its end and hands over all of its stdout at once. process.run without the line accumulator, and with the newlines left in.

process.capture("date", { "+%F" }, function(stdout, code)
    if code == 0 then today = stdout:gsub("\n$", "") end
end)

process.detach

Starts a program that stops being the shell’s: its own session, reparented to init, stdio on /dev/null. It outlives reloads, Renderer replacement and the shell itself.

return panel {
    id = "dock", layer = "top", anchor = { bottom = true },
    child = rect {
        padding = 8,
        on_click = function()
            process.detach("xdg-open", { os.getenv("HOME") or "/" })
        end,
        children = { text { content = "Home folder" } },
    },
}

session_process

Declares one named, long-running program that the Supervisor holds. It survives reloads and Renderer replacement, and its state comes back as signals, so there is no pid file or poll. Use process.run when you need the output.

-- SIGINT lets the recorder finish the file; shutdown uses it too.
local recorder = session_process { name = "recorder", stop_signal = "INT" }
local recording = recorder.running:map(function(running) return running == true end)

local function toggle()
    if recording:get() then
        recorder:stop()
    else
        local file = (os.getenv("HOME") or "") .. "/Videos/" .. os.date("%Y%m%d_%H%M%S") .. ".mp4"
        recorder:start("gpu-screen-recorder", { "-w", "screen", "-o", file })
    end
end

return panel {
    id = "rec", layer = "top", anchor = { top = true, right = true },
    child = rect {
        on_click = toggle,
        children = {
            text {
                content = computed({ recording, recorder.start_error }, function(on, err)
                    if err and err ~= "" then return "Recorder failed: " .. err end
                    return on and "● REC" or "Record"
                end),
                foreground = recording:map(function(on) return on and "#F38BA8" or "#CDD6F4" end),
            },
        },
    },
}

session_process { name, stop_signal? } returns a handle. name must be non-empty; declaring the same name again, on reload or from another module, returns the same handle and re-reads only stop_signal. stop_signal defaults to "TERM". Any other key raises.

Signal names drop the SIG prefix: TERM, INT, HUP, QUIT, USR1, USR2, KILL, STOP, CONT.

Handle signals, each nil until mantle.processes first pushes (and in mantle check):

Handle methods (call with :):

At shutdown the Supervisor runs stop() on every running program and waits for each. The whole state is also readable as mantle.processes (capabilities).

How do I…

Poll a command every N seconds

A reload kills the df in flight and clears the interval, and the top-level call starts a fresh one.

local disk = state("disk_usage", "")

local function poll()
    local lines = {}
    process.run("df", { "--output=pcent", "/" }, function(line, stream)
        if stream == "stdout" then lines[#lines + 1] = line end
    end, function(code)
        if code == 0 and lines[2] then disk:set(lines[2]:match("%d+%%") or "") end
    end)
end
poll()
interval(30000, poll)

return panel {
    id = "disk", layer = "top", anchor = { top = true },
    child = text { content = disk:map(function(value) return "/ " .. value end) },
}

Follow a long-running command’s output

A process.run child that never exits keeps calling on_line. Start it at the top level: each save kills the old one and starts one fresh. The retry below runs after the child exits on its own; the one a reload’s on_exit(nil) arms is cleared with the old timers.

local title = state("now_playing", "")

local function follow()
    process.run("playerctl", { "--follow", "metadata", "--format", "{{artist}} - {{title}}" },
        function(line, stream)
            if stream == "stdout" then title:set(line) end
        end,
        function() timer(5000, follow) end)
end
follow()

return panel {
    id = "media", layer = "top", anchor = { top = true },
    child = text { content = title, elide = "end", max_width = 300 },
}

Gotchas

See also: scripting (timer, json, log, persistent_table), runtime (reloads, logging), signals (state), processes capability (mantle.processes), cli (mantle log).

Source: process, spawn and reap, process registry, session process, processes controller.