QuicxDocs

Architecture

One daemon, three role-based endpoints, one allocator. Every piece is in one diagram, and none of them is optional.

Producers

  • Producer A
  • Producer B
  • quicx status (CLI)

Quicx daemon

  1. Connection router
  2. Task queue
  3. Dispatcher
  4. Worker pool

apool allocator

Every task above is one block from the fixed budget: O(1) alloc / free, with pages going to the sizes that arrive.

Workers

  • Worker 1
  • Worker 2
  • Worker N
The daemon, its three role-based endpoints and the allocator behind them.

Quicx is deliberately flat. A single daemon process owns the task queue, the worker pool and the apool allocator. Producers and workers are plain TCP clients that speak the same protocol, QXP, and the first frame they send tells the daemon which role they’re playing.

The Quicx Java client plays both roles: QuicxClient is a producer and QuicxWorker a worker. The Java quick start runs one of each against a local daemon, so every path below can be watched in a terminal.

There are four message paths, one in each direction across the two hops in the diagram:

producer → daemon
MSG_SUBMIT lands a new task. The daemon responds with either MSG_OK {task_id} or MSG_ERROR {code}, always within one round-trip.
daemon → worker
Workers announce themselves with MSG_READY and block reading. The daemon pushes MSG_TASK frames to the first idle worker as soon as one is queued. If the queue is empty, the worker simply stays blocked. MSG_WAIT is defined on the wire but nothing in the daemon actually sends it.
worker → daemon
MSG_DONE {task_id} on success, MSG_FAILED {task_id, reason} on failure. MSG_HEARTBEAT / MSG_PONG keep the socket from half-closing under long idle.
daemon → producer
As of v1.0.3, the daemon forwards the worker’s outcome back over the producer’s original connection: MSG_DONE {task_id} or MSG_FAILED {task_id, reason} with the worker’s real reason. A producer’s socket now spans the task’s full lifetime, not just the initial submit.

Why a single daemon?#

Multi-node queues pay a tax in the form of leader elections, replication logs and consistent hashing. Quicx is optimised for the much more common case where your queue lives on the same host (or at worst, the same availability zone) as your producers and workers. One daemon measured 81,900 tasks/sec end to end on a single thread over loopback, at a 49 µs median (see Benchmarks for the harness and the caveats). It does that inside one fixed memory budget: allocation is O(1), and memory a burst used goes back to the OS once the queue drains.

Scaling horizontally means running multiple independent Quicx daemons behind a simple TCP load balancer. A task never crosses daemons: it’s queued, run and completed on whichever instance the producer happened to land on, so there’s still no replication to coordinate. The one thing that changed in v1.0.3: since completion is now reported back on the producer’s original connection, that socket has to stay pinned to its daemon for the life of the task, not just for the initial submit.