How I built a scriptable Lua extension engine inside my C++ activity tracker (and almost lost my mind to deadlocks)

#cpp #opensource #programming #extensions

Hey!

I've been building HPR, an open source activity tracker and window tracker written in C++23. It watches your active window, builds a history of where your time went, and runs locally with zero accounts and zero telemetry. Think of it as a lightweight ActivityWatch alternative with native Wayland support.

At some point I decided it wasn't enough to just track windows. I wanted people to be able to extend it. So I built a Lua extension engine into it. Here's how that went.

The basic idea

Every .lua file you drop into the extensions folder gets picked up automatically. HPR scans the directory recursively, loads each file into its own sol::state, registers the API, and spins up a dedicated thread for it. Each extension runs completely isolated from everything else. A slow or broken extension can't freeze the UI or corrupt the tracking loop.

The lifecycle is simple. You define three functions:

function init()
    return 500 -- tick interval in ms
end

function onTick(delta)
    -- called every 500ms
end

function onExit()
    -- cleanup
end

init returns how often you want onTick to fire. That's it. Everything else is opt-in through the API.

The API

This is where it gets actually useful. From Lua, an extension can:

Read the currently focused window with HPR.getCurrentWindow_E()
Query and write to the SQLite database directly with HPR.dbQuery_E() and HPR.dbExecute_E()
Subscribe to internal events like WINDOW_CHANGED, MIDNIGHT_ROLLOVER, HISTORY_LOADED_SINGULAR
Register completely custom window detection backends for compositors HPR doesn't natively support
Set UI properties and register callbacks on the Slint UI from Lua
Make HTTP requests, start an HTTP server, parse JSON, read and write CSV files
Stop and resume the window tracking loop entirely

That last one sounds weird but its how the AFK detection works in one of the extensions I built, more on that in a second.

The hardest parts

Honestly the code itself wasnt the worst part. The worst part was deadlocks.

The Lua state is not thread safe. The Slint UI is also not thread safe and must only be touched from its event loop thread. The shared app state has its own mutex. So you have extension threads, the Slint event loop thread, the window poller thread, and the database writer thread all needing to talk to each other without stepping on each other.

The solution was a recursive_mutex per extension that wraps every Lua call, and slint::invoke_from_event_loop for anything that touches the UI. Callbacks registered from Lua that get fired by Slint acquire the Lua mutex before calling back into Lua. It took a while to get right.

The other fun one was cyclic table detection. If a Lua extension pushes a self referential table into a UI property, without protection you get a stack overflow and a segfault. I added a visited set that tracks table pointers during the conversion and bails out with an error message if it sees a cycle instead of recursing forever.

A real example: impersonating ActivityWatch

One of the extensions I wrote is called AW Parasite. It starts an HTTP server on port 5600, which is the default ActivityWatch port. aw-watcher-web and aw-watcher-afk both think they're talking to a real ActivityWatch instance. They send heartbeats, the extension processes them, accumulates URL time and AFK status, writes everything into the HPR SQLite database, and updates the UI through HPR.setUiProperty_E.

When the user goes AFK, the extension calls HPR.stopTracking_E() to pause the main activity window tracker. When they come back it calls HPR.startTracking_E(). The whole thing is about 200 lines of Lua and it works on both Wayland and Windows because its just HTTP.

Hot reload

You can load, unload and reload individual extensions from the UI without restarting HPR. There's also a rescan button that picks up new .lua files you dropped in after launch. Unloading sets running = false on the extension's thread and gives it 450ms to exit cleanly. If it doesnt, the thread gets detached and a warning is logged. Native extensions (.dll / .so) are also supported for cases where Lua isnt enough, though those run outside the sandbox.