Quicx Documentation

curl -fsSL https://quicx.dev/install.sh | sh

curl -fsSL https://quicx.dev/install.sh -o install-quicx.sh
less install-quicx.sh
sh install-quicx.sh

What the installer does

1 · detect

Reads uname -s and uname -m to pick the right artifact — linux-x86_64, linux-arm64, darwin-x86_64 or darwin-arm64.

2 · fetch

Downloads the signed release tarball from releases.quicx.dev over HTTPS.

3 · verify

Checks the SHA‑256 against the signed SHA256SUMS file. Exits non-zero if the hash does not match.

4 · install

Places the quicx binary in /usr/local/bin (or ~/.local/bin if the user does not have root). Writes a default quicx.conf to ~/.config/quicx/.

5 · verify

Runs quicx version and prints the resolved install path so you know the PATH lookup works.

Verify it worked

user@host ~ % quicx version
quicx v1.0.0

1. Step01

   Start the daemon

   Quicx needs a configuration file to know which TCP port to bind and how to carve up the PMAD pool. The installer writes a sensible default to ~/.config/quicx/quicx.conf — see Configuration for every knob.

   ~ $

   copy

   user@host ~ $ quicx start --config /etc/quicx/quicx.conf
   config loaded: /etc/quicx/quicx.conf
   quicx v1.0.0 starting
     port:    16381
     classes: 32 64 128 256 512 1024
   quicx listening on port 16381 [kqueue]
   quicx cli socket: /tmp/quicx.sock

2. Step02

   Add the Java client to your build

   The client lives on Maven Central under dev.quicx:quicx-client. It’s a tiny jar (no transitive dependencies) that speaks the Quicx binary protocol directly.

   MavenGradle (Kotlin)Gradle (Groovy)

   pom.xml

   copy

   <dependency>
     <groupId>dev.quicx</groupId>
     <artifactId>quicx-client</artifactId>
     <version>1.0.0</version>
   </dependency>

3. Step03

   Submit your first task

   QuicxClient is a stateless, thread-safe producer handle. Every submit() opens a connection, sends MSG_SUBMIT, reads the acknowledgment, and closes — so you can treat it exactly like an HTTP call. The full wire format is documented in Binary Protocol.

   Producer.java

   copy

   import dev.quicx.QuicxClient;
   
   public class Producer {
       public static void main(String[] args) throws Exception {
           try (QuicxClient client = new QuicxClient("localhost", 16381)) {
               int taskId = client.submit(
                   "send_email",
                   "{\"to\":\"user@gmail.com\"}"
               );
               System.out.println("accepted task id = " + taskId);
           }
       }
   }

4. Step04

   Run a worker

   QuicxWorker connects, announces itself with MSG_READY and then blocks receivingMSG_TASK frames. Register one handler per task type; the worker reconnects automatically on daemon restarts.

   EmailWorker.java

   copy

   import dev.quicx.QuicxWorker;
   
   public class EmailWorker {
       public static void main(String[] args) throws Exception {
           new QuicxWorker("localhost", 16381)
               .handle("send_email", payload -> {
                   String body = new String(payload, "UTF-8");
                   System.out.println("delivering: " + body);
                   // ... do the work ...
               })
               .start();   // blocks — runs until the process is killed
       }
   }

# Quicx config
[server]
port = 16381

[allocator]
pool_size = 1048576
class = 32,10
class = 64,25
class = 128,25
class = 256,20
class = 512,12
class = 1024,8

[server]

port

TCP port the daemon binds to. Producers and workers both dial the same port — routing is decided by the first message they send (MSG_SUBMIT vs MSG_READY). Default: 16381.

[allocator]

pool_size

Total bytes reserved via a single mmap call. Default is 1048576 (1 MiB). The allocator never grows past this number — if you exhaust it, newMSG_SUBMIT frames are rejected with MSG_ERROR 0x01 (queue full).

class = SIZE,PCT

Declares one size class: SIZE is the block size in bytes, PCT is the percentage of the pool that belongs to that class. Declare the classes in ascending SIZE order. The percentages must sum to 100; if they don’t, the daemon refuses to start.

Tuning rules of thumb

One daemon · zero moving parts

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. No streaming, no batching, no surprises.

daemon → worker

Workers announce themselves with MSG_READY and block reading. The daemon pushes MSG_TASK frames to the first idle worker. If the queue is empty, the daemon replies with MSG_WAIT instead of keeping a pending read open.

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.

Why a single daemon?

Architecture

Public API

The thin facade in incPMAD.h — pmad_init, pmad_alloc, pmad_free, pmad_destroy. This is the entire contract the daemon consumes.

Size Class Table

A flat array [MAX_SIZE / ALIGNMENT] maps a requested byte-count directly to the correct size-class descriptor — an O(1) table lookup, no branches.

Free Lists

Each size class owns a singly-linked intrusive free list. A pop is a pointer dereference; a push is a pointer swap. No atomics on the fast path — the daemon serialises through its own router, so locks are structurally unnecessary.

Memory Pool

One mmap region split into contiguous runs of blocks, one run per class, sized by the user percentages. Each block carries a 16-byte BlockHeader (next pointer + class ID) so deallocations need no external metadata.

Benchmarks

Reference configurations

Tear-down

Frame header

version

Protocol revision. Currently 0x01. The daemon rejects any other version with MSG_ERROR 0x02 so protocol evolution is additive and opt-in.

type

Message opcode — one of the 11 types below. The daemon routes on type alone; producers and workers speak the same header shape.

length

32-bit big-endian unsigned integer: the payload size in bytes. Zero is legal for MSG_READY, MSG_WAIT, MSG_HEARTBEAT, MSG_PONG and MSG_STATS.

payload

Exactly length bytes. The per-type layouts below are the full contract — there is no escaping, no delimiters and no padding.

Message types

Payload formats

[type_len : 1 byte][type : type_len bytes][payload : rest of bytes]

type = "send_email"
payload = {"to":"user@gmail.com"}
bytes   = [10][send_email][{"to":"user@gmail.com"}]

[task_id : 4 bytes]

task_id = 0x00000A42  →  accepted task id = 2626

[error_code : 1 byte][message : rest of bytes]

(no payload — length = 0)

Sent once per connection, immediately after connect, to register
the socket as an idle worker. The daemon replies with MSG_TASK or
MSG_WAIT.

[task_id : 4 bytes][type_len : 1 byte][type : type_len bytes][payload : rest]

Mirror of MSG_SUBMIT with the task id prepended. The worker dispatches
by type and replies with MSG_DONE or MSG_FAILED carrying the same id.

[task_id : 4 bytes]

Confirms successful completion. The daemon frees the task slot back
to PMAD before responding to any producer waiting on this id.

[task_id : 4 bytes][reason : rest of bytes]

reason is a UTF-8 string propagated verbatim to producers that
observe the task, and logged by the daemon. Keep it short — it lives
in the same size class as the original payload.

(no payload — length = 0)

Sent in place of MSG_TASK when the queue is empty. The worker keeps
the socket open and issues another MSG_READY after a short backoff.

(no payload — length = 0)

Liveness probe. Either side may send it; the receiver replies with
MSG_PONG. Intended for long-idle worker sockets behind stateful
load balancers.

(no payload — length = 0)

The only valid reply to MSG_HEARTBEAT. Shape-symmetric with
MSG_HEARTBEAT for trivial framing.

(no payload — length = 0)

Requests a one-shot metrics snapshot. The daemon responds with
MSG_STATS_RESPONSE.

[queue_depth : 4 bytes][workers_total : 4 bytes][workers_idle : 4 bytes][pmad_bytes_used : 8 bytes][pmad_bytes_total : 8 bytes]

All integers are big-endian. The 28-byte body is a fixed shape so
dashboards can parse it without a schema.

Add it to your build

<dependency>
  <groupId>dev.quicx</groupId>
  <artifactId>quicx-client</artifactId>
  <version>1.0.0</version>
</dependency>

QuicxClient — producers

new QuicxClient(host, port)

Construct a reusable handle. No network work is performed here.

int submit(type, byte[])

Send a MSG_SUBMIT with a raw payload. Returns the 32-bit task id assigned by the daemon. Throws QuicxException on MSG_ERROR.

int submit(type, String)

Convenience overload: UTF-8 encodes the payload for you.

close()

Idempotent. Tears down any transport resources. Use try-with-resources.

import dev.quicx.QuicxClient;
import dev.quicx.QuicxException;

try (QuicxClient client = new QuicxClient("localhost", 16381)) {
    int id = client.submit(
        "resize_image",
        new byte[]{ 0x01, 0x02, 0x03 /* raw bytes */ }
    );
    System.out.println("accepted id = " + id);
} catch (QuicxException e) {
    // daemon rejected the task — rate-limit, retry or surface upstream
    System.err.println("rejected: " + e.getMessage());
}

QuicxWorker — consumers

new QuicxWorker(host, port)

Construct a worker. No network work happens until start().

handle(type, handler)

Register a TaskHandler for a task type. Returns this for chaining. Handlers are keyed by the same type string the producer sent in MSG_SUBMIT.

start()

Connect, send MSG_READY and enter the dispatch loop. Blocks forever. On an unexpected disconnect the worker sleeps for 3 s and reconnects — your handlers keep running across daemon restarts.

close()

Flips the running flag, closes the socket and unblocks start(). Safe to call from a shutdown hook.

import dev.quicx.QuicxWorker;

public class Worker {
    public static void main(String[] args) throws Exception {
        QuicxWorker worker = new QuicxWorker("localhost", 16381)
            .handle("send_email", payload -> {
                String body = new String(payload, "UTF-8");
                EmailService.deliver(body);
            })
            .handle("resize_image", payload -> {
                Images.resize(payload);
            });

        Runtime.getRuntime().addShutdownHook(new Thread(() -> {
            try { worker.close(); } catch (Exception ignored) {}
        }));

        worker.start();   // blocks — the dispatch loop owns this thread
    }
}

QuicxException

package dev.quicx;

public class QuicxException extends RuntimeException {
    public QuicxException(String message) { super(message); }
    public QuicxException(String message, Throwable cause) {
        super(message, cause);
    }
}

• v1.0.02026-04-21Current
  • First public release.
  • Binary protocol frozen — 12 message types, 6-byte header, versioned.
  • PMAD v1 — O(1) slab allocator with user-defined size classes.
  • Java client published to Maven Central as dev.quicx:quicx-client.
  • Install script for Linux (x86_64, arm64) and macOS (Intel, Apple Silicon).