Quick Start in Java
Start the daemon with a 256 KiB memory budget, run a Java worker and a producer that gives its tasks value levels, then fill the budget and watch Quicx keep the valuable task. About a minute, with no build tool: Java 11 runs each file straight from source.
You need the quicx binary and Java 11 or later. Installing Quicx is one command, and quicx version should then print quicx v2.1.0. Each program below is a single file that java runs straight from source, so the client jar on the classpath is the only setup. In a Maven or Gradle project, take the dependency from the Java client’s build setup instead and run the same classes.
You will use three terminals in one empty directory: one for the daemon, one for a worker and one for the producers.
Step 01: Start the daemon with a memory budget
Create a two-line
quicx.conf. The budget is tiny on purpose, so that a later step can fill it in under a second; the default is 8 MiB.quicx.conf[memory] pool_size = 256KStart the daemon in the first terminal. It stays in the foreground and prints what it is running with:
terminal 1: the daemonuser@host qs $ quicx start --config quicx.confconfig loaded: quicx.confquicx v2.1.0 starting port: 16381 pool: 262144 bytes, 16 KiB pages given to block sizes on demand apool: reserve, hardening, purge; when full: value pages: 12 for tasks (4 kept warm, 0 reserved), 3 for connections and workersquicx listening on port 16381 [kqueue]quicx cli socket: /tmp/quicx.sock256 KiB is 16 pages of 16 KiB: three hold connections and workers, one holds the records that describe the pages, and twelve hold tasks. The daemon maps all of it once, at startup, and never asks the OS for more.
when full: valueis the default admission rule: when the budget is full, a new task may push out a waiting task of a lower value level. On Linux the event loop reads[epoll]instead of[kqueue].Step 02: Get the Java client
The client,
dev.quicx:quicx-client, is one 30 KB jar with no dependencies. Download it from Maven Central into the same directory:terminal 3user@host qs $ curl -fsSLO https://repo1.maven.org/maven2/dev/quicx/quicx-client/2.1.0/quicx-client-2.1.0.jarStep 03: Run a worker
A worker connects, tells the daemon which task types it handles, and runs tasks one at a time. This one prints every task it runs.
handleTaskgives the handler the whole task, including the id the daemon gave it; when the handler returns, the worker reports the task done.Worker.javaimport dev.quicx.QuicxWorker; public class Worker { public static void main(String[] args) { QuicxWorker worker = new QuicxWorker("localhost", 16381) .handleTask("invoice", task -> System.out.println("ran invoice #" + task.id() + " " + task.payloadAsString())) .handleTask("thumbnail", task -> System.out.println("ran thumbnail #" + task.id() + " " + task.payloadAsString())); Runtime.getRuntime().addShutdownHook(new Thread(worker::stop)); worker.start(); // blocks until Ctrl-C } }Run it in the second terminal and leave it running:
terminal 2: the workeruser@host qs $ java -cp quicx-client-2.1.0.jar Worker.javaNov 20, 2026 12:17:50 AM dev.quicx.QuicxWorker startINFO: connected to quicxd at localhost:16381, handling [invoice, thumbnail]The
INFOline is the worker’s own log. It goes throughSystem.Logger, so in an application it ends up wherever the rest of your logging goes.Step 04: Submit tasks with value levels
Every task carries a value level from 0, the least valuable, to 15, which is never evicted. A submit without a level gets 8. Waiting tasks with a higher level reach workers first, and when the budget is full the level decides what is kept. This producer queues a thumbnail at level 2 and an invoice at level 12, then submits a second invoice and waits until a worker has run it.
Producer.javaimport dev.quicx.QuicxClient; import dev.quicx.TaskResult; import java.time.Duration; public class Producer { public static void main(String[] args) { try (QuicxClient client = new QuicxClient("localhost", 16381)) { // value levels: 0 (least valuable) to 15 (never evicted); a plain submit is 8 int thumb = client.submit("thumbnail", "photos/cat.jpg", 2); int inv = client.submit("invoice", "order-1001", 12); System.out.println("queued thumbnail #" + thumb + " and invoice #" + inv); // wait until a worker has run it TaskResult r = client.submitAndWait("invoice", "order-1002", 12, Duration.ofSeconds(5)); System.out.println("invoice #" + r.taskId() + (r.isDone() ? " done" : " failed: " + r.failureReason().get())); } } }terminal 3: the produceruser@host qs $ java -cp quicx-client-2.1.0.jar Producer.javaqueued thumbnail #1 and invoice #2invoice #3 doneAt the same moment, the worker prints:
terminal 2: the workerran thumbnail #1 photos/cat.jpgran invoice #2 order-1001ran invoice #3 order-1002With a worker idle, each task goes to it as soon as it arrives, so they run in the order they were sent. Levels only change the order of tasks that are waiting, which is what the next part shows.
When the budget is full#
Stop the worker with Ctrl-C, so that nothing takes tasks off the queue, and run the producer below. It fills the budget with level-2 thumbnails until the daemon refuses one, then sends a level-12 invoice. It keeps the result of its very first thumbnail, to show what became of it.
import dev.quicx.QuicxClient;
import dev.quicx.QuicxRejectedException;
import dev.quicx.TaskResult;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.TimeUnit;
public class Flood {
public static void main(String[] args) throws Exception {
try (QuicxClient client = new QuicxClient("localhost", 16381)) {
// keep the result of the oldest thumbnail, to see what happens to it
CompletableFuture<TaskResult> first = client.submitAsync("thumbnail", "img-0", 2);
// fill the budget with level-2 thumbnails; no worker is running
int queued = 1;
try {
while (true) {
client.submit("thumbnail", "img-" + queued, 2);
queued++;
}
} catch (QuicxRejectedException e) {
System.out.println("budget full after " + queued + " thumbnails: " + e.code());
}
// a more valuable task still gets in: it evicts the oldest thumbnail
int id = client.submit("invoice", "order-1003", 12);
System.out.println("invoice accepted as #" + id);
TaskResult r = first.get(5, TimeUnit.SECONDS);
System.out.println("thumbnail #" + r.taskId() + " evicted: " + r.isEvicted());
// another thumbnail has nothing less valuable to push out
try {
client.submit("thumbnail", "img-late", 2);
} catch (QuicxRejectedException e) {
System.out.println("late thumbnail refused: " + e.code());
}
}
}
}user@host qs $ java -cp quicx-client-2.1.0.jar Flood.javabudget full after 2448 thumbnails: QUEUE_FULLinvoice accepted as #2452thumbnail #4 evicted: truelate thumbnail refused: QUEUE_FULLuser@host qs $ quicx status quicx v2.1.0 · pid 30155 · up 0h 0m 08s tasks submitted 2,452 completed 3 ░░░░░░░░░░░░░░░░░░░░ 0.1% failed 0 0.0% evicted 1 0.0% for more valuable tasks in flight 2,448 = 2448 queued + 0 running queued 2,448 ... memory 12 / 12 pages ████████████████████ 100.0% pool 207.9 KiB, 16 KiB pages · 1 size in use 80B 2,448 / 2,448 ████████████████████ 100.0% 12 pagesEach thumbnail takes an 80-byte block: a 64-byte record plus its payload, rounded up to 16 bytes. A 16 KiB page holds 204 of those, so the twelve task pages hold exactly 2,448, and the next thumbnail was refused with QUEUE_FULL. How many tasks fit has the formula for any payload and budget.
When the invoice arrived, the budget was full, so the daemon evicted the oldest waiting task with the lowest level below 12: thumbnail #4, the first one Flood sent (#1 to #3 were the earlier producer’s). Its producer was told through the task’s result, where isEvicted() is true. An evicted task never ran; send it again later if it still matters. The late thumbnail was refused because no waiting task had a lower level than its own: tasks of the same level never evict each other. That is also why a queue fed only plain submits, which are all level 8, simply refuses new tasks once it is full.
Eviction needs one more condition: the freed memory has to fit the new task, which means the same block size, or the last block on its page. Here every task is an 80-byte block. Start the worker again, and the invoice, the last task to arrive, runs first:
user@host qs $ java -cp quicx-client-2.1.0.jar Worker.javaNov 20, 2026 12:17:57 AM dev.quicx.QuicxWorker startINFO: connected to quicxd at localhost:16381, handling [invoice, thumbnail]ran invoice #2452 order-1003ran thumbnail #5 img-1ran thumbnail #6 img-2...ran thumbnail #2451 img-2447The same rule at scale, on the real daemon under overload, is measured in Benchmarks: when the budget is full.
Common errors and how to fix them#
Each entry is the message as the daemon prints it, or as the client puts it in the exception.
- cannot connect to quicxd at localhost:16381
- A
QuicxConnectionException: no daemon listens on that host and port. Start it withquicx start, or give the client and the worker the port it uses. - bind: Address already in use
- From
quicx start: another daemon already has port 16381. Stop that one with Ctrl-C in its terminal, or start this one with--port 16401and use that port in the Java code. See several daemons on one machine. - error: quicx.conf:2: pool_size must be a byte count such as 8388608 or 8M, not '8MB'
- The config is checked strictly and names the file and line. Sizes take
K,MorG(1024-based);8MBis refused as ambiguous. - quicxd refused: out of memory (QUEUE_FULL)
- A
QuicxRejectedExceptionwhoseisQueueFull()is true: the budget is full and nothing waiting has a lower level than the new task. Run more workers, send it again later, give it a higher level, or raisepool_size. - quicxd refused: parse error (INVALID_MESSAGE)
- A submit with a level reached a daemon older than 2.1.0, which does not know
MSG_SUBMIT_VALUED. The usual cause is an oldquicxearlier on thePATH: checkquicx versionand run the installer again. - payload of 2000 bytes is too large: with the task type 'thumbnail' at most 1014 bytes fit in one QXP frame of 1024 bytes
- An
IllegalArgumentException, thrown before anything is sent. Put large data where the workers can read it and send its path or id, as the examples here do. Bigger tasks need a daemon built for them; see the Java client’s limits. - no result within 5000 ms
- A
QuicxExceptionfromsubmitAndWait: no worker ran the task in time, usually because none is running. The timeout only ends the waiting. The task stays queued and runs when a worker connects. - no handler for task type resize
- The failure reason of a task that reached a worker without a handler for its type;
failureReason()returns it, and the worker logs it as a warning. Register the exact type withhandleorhandleTask, or set afallback.
Next steps#
Stop the daemon with Ctrl-C, or quicx stop from another terminal. Tasks still queued are lost when it stops: Quicx keeps them in memory only. From here:
- Java client API reference: every method of
QuicxClientandQuicxWorker, the threading model, error handling and the Maven and Gradle coordinates. - Configuration: the memory budget, the admission rule and how many tasks a budget holds.
- CLI reference:
quicx status,quicx stopand running several daemons on one machine. - Benchmarks: throughput, latency, capacity and value-aware eviction under overload, all measured.
- Limitations: no persistence, at-most-once delivery, and everything else Quicx deliberately does not do.
- QXP protocol: the frames behind every call above, enough to write a client in another language.