QuicxDocs

CLI Reference

quicx is the single binary that ships with the release. Running it with no arguments prints the same usage you see below.

~ $ quicx
quicx v2.1.0 — lightweight task queue daemon usage:  quicx start [--config FILE] [--port N]  quicx stop [--port N]  quicx status [--port N]  quicx version
quicx start [--config FILE] [--port N]start the daemon in the foreground

Binds the port, maps the memory budget once, and begins accepting connections. Runs in the foreground, so the calling shell owns the process. Pair with systemd, tmux, launchd or your container supervisor for lifecycle management.

--config is optional. When omitted, the daemon starts with the built-in defaults (port 16381, an 8 MiB budget, apool with reserve, hardening and purge on). Pass a quicx.conf to override any or all values; --portoverrides the file’s port.

quicx stop [--port N]gracefully stop the local daemon

Sends SIGTERM to the pid recorded in /tmp/quicx.pid, or in /tmp/quicx-<port>.pid for a daemon on another port. The daemon exits and the OS takes its memory back. Tasks still in the queue are lost, as on any restart (see Limitations).

quicx status [--port N]live observation of the running daemon

Opens a short-lived control connection over the /tmp/quicx.sock Unix socket (/tmp/quicx-<port>.sock with --port) and sends MSG_STATS, then renders the MSG_STATS_RESPONSE as a human-readable table. Shows uptime, task counters (including in-flight, derived as submitted − completed − failed), pages in use out of the pool, and every block size that holds pages with its live blocks, capacity and page count. Safe to script: it exits non-zero if the daemon is unreachable.

~ $
user@host ~ $ quicx status   quicx v2.1.0  ·  pid 8278  ·  up 0h 0m 00s   tasks     submitted       1,500            completed           0   ░░░░░░░░░░░░░░░░░░░░     0.0%            failed              0                            0.0%            in flight       1,500   = 1500 queued + 0 running            queued          1,500   workers   busy                0   ░░░░░░░░░░░░░░░░░░░░     0.0%            idle                0            total               0   · 0 registered since start   memory    32 / 508 pages          █░░░░░░░░░░░░░░░░░░░     6.3%            pool 7.95 MiB, 16 KiB pages · 2 sizes in use            176B    1,200 /   1,209  ███████████████████░    99.3%    13 pages           976B      300 /     304  ███████████████████░    98.7%    19 pages user@host ~ $

Above: 1,200 tasks of 100 B and 300 of 900 B waiting, no worker connected. Since 2.0 the memory block counts pages. A size appears only while it holds some, and its capacity grows and shrinks with the pages it owns. Redesigned in v1.0.3: bar charts, thousands separators and human-readable byte sizes replace the raw counters from earlier releases. New fields exposed on the wire: workers_registered (ever registered, not just currently live), pool_size (bytes requested from the OS), usable_bytes (after the metadata carve-out) and used_bytes (metadata + live blocks).

quicx versionprint the binary version

Prints the version on one line, for example quicx v2.1.0.

Several daemons on one machine#

Each daemon has its own port, memory budget, CLI socket and pid file, so one machine can run a queue per application or per customer, each held to its own limit. The default port keeps /tmp/quicx.sock and /tmp/quicx.pid; any other port uses /tmp/quicx-<port>.sock and /tmp/quicx-<port>.pid.

~ $ two customers, one machine
quicx start --port 16401 --config customer-a.confquicx start --port 16402 --config customer-b.confquicx status --port 16401quicx stop --port 16402

Measured with ten daemons of 8 MiB on one Mac: filling one to its limit (46,593 tasks, then ERROR 0x01) left the other nine accepting every task, and each quicx status --port reported its own daemon. An idle daemon takes about 1.4 MiB. Memory is fenced per daemon; CPU and network are shared as usual.