Java Client
dev.quicx:quicx-client 2.1.0 is a small, dependency-free Java 11+ library. QuicxClient submits tasks, with value levels if you want, and can wait for their result; QuicxWorker runs them, reconnecting and reporting on its own.
This page is the reference for the library: how to add it to a build, which daemon versions it works with, every public method of QuicxClient and QuicxWorker, the threads it runs and the errors it throws. To see a producer and a worker run first, follow the quick start, a first task queue in Java. The Javadoc is on javadoc.io and the source is Quicx-Engine/Quicx-Java on GitHub, MIT licensed.
Add it to your build#
<dependency>
<groupId>dev.quicx</groupId>
<artifactId>quicx-client</artifactId>
<version>2.1.0</version>
</dependency>The artifact is on Maven Central, so no extra repository is needed. The jar is about 30 KB and has no dependencies of its own. On the module path its name is dev.quicx.client:
module com.example.orders {
requires dev.quicx.client;
}Compatibility#
| quicxd 1.0.3 to 2.0.x | quicxd 2.1.0 and later | |
|---|---|---|
| submit, results, workers | yes | yes |
value levels and isEvicted() | refused with INVALID_MESSAGE | yes |
maxBody above 1,024 bytes | no | with a daemon built with make MAX_PAYLOAD=N |
Java 11 or later. Client 2.1.0 was tested against quicxd 2.0.0 and 2.1.0, on Java 11, 17 and 21. Code written for client 2.0 compiles and behaves the same with 2.1. A daemon is installed with one command, see Installation; quicx version tells you which one is running.
QuicxClient for producers#
A QuicxClient keeps one TCP connection to the daemon and uses it for every call; if the connection breaks, the next call opens a new one. One client can be shared by any number of threads, so create it once rather than once per task.
- new QuicxClient(host, port)
- A client with default settings. It connects on the first submit.
- QuicxClient.builder()
- Settings, each with its default:
host(localhost),port(16381),connectTimeout(5 s),responseTimeout(10 s, how long a submit waits for the daemon to accept the task) andmaxBody(1,024 bytes, only to be raised for a daemon built withmake MAX_PAYLOAD=N).build()returns the client. - int submit(type, payload)
- Sends
MSG_SUBMITand returns the task id once the daemon has queued the task. Does not wait for a worker. The payload is abyte[]or aString(sent as UTF-8). - int submit(type, payload, level)
- Sends
MSG_SUBMIT_VALUEDwith a value level from 0 to 15 (quicxd 2.1.0 and later). Higher levels reach workers first, and when the budget is full a task can push out a waiting task of a lower level.QuicxClient.DEFAULT_LEVEL(8) is what a plain submit gets;QuicxClient.CRITICAL_LEVEL(15) is never evicted. - TaskResult submitAndWait(type, payload, [level,] timeout)
- Submits and blocks until a worker reports
MSG_DONEorMSG_FAILED, which the daemon passes back to the producer, or until the daemon evicts the task. ThrowsQuicxExceptionif no result arrives withintimeout. - CompletableFuture<TaskResult> submitAsync(type, payload, [level])
- The same without blocking. Results are matched by task id, so they can arrive in any order. If the daemon refuses the task, the future fails with QuicxRejectedException.
- host(), port(), maxBody()
- The settings the client was built with.
- DEFAULT_PORT, DEFAULT_LEVEL, CRITICAL_LEVEL
- 16381, 8 and 15.
- close()
- Closes the connection. Calls still waiting fail with QuicxConnectionException. Calling it twice does nothing.
A TaskResult says how a task ended: taskId(), isDone(), isFailed(), isEvicted() and failureReason(), an Optional<String> with the worker’s reason (at most 63 bytes). An evicted task also counts as failed, with the reason evicted, so check isEvicted() first: an evicted task never ran.
import dev.quicx.QuicxClient;
import dev.quicx.TaskResult;
import java.time.Duration;
QuicxClient client = QuicxClient.builder()
.host("queue.internal")
.connectTimeout(Duration.ofSeconds(2))
.responseTimeout(Duration.ofSeconds(5))
.build();
int id = client.submit("send_email", "{\"to\":\"ana@example.com\"}");
// quicxd 2.1+: a frame worth keeping, and a command that is never evicted
client.submit("frame", "/cam/0/000124.jpg", 12);
client.submit("stop", "", QuicxClient.CRITICAL_LEVEL);
TaskResult result = client.submitAndWait("resize_image", imageBytes, Duration.ofSeconds(30));
if (result.isFailed()) {
System.err.println("resize failed: " + result.failureReason().get());
}
// an ordinary frame: find out later whether a more valuable task pushed it out
client.submitAsync("frame", "/cam/0/000125.jpg", 4).thenAccept(r -> {
if (r.isEvicted()) retryLater("/cam/0/000125.jpg");
});QuicxWorker for consumers#
A QuicxWorker registers with MSG_READY and runs the tasks the daemon sends it, one at a time. When a handler returns, the worker replies MSG_DONE; when it throws, MSG_FAILEDwith the exception’s class and message.
- new QuicxWorker(host, port)
- A worker with default settings.
- QuicxWorker.builder()
host,port,connectTimeout(5 s),heartbeatInterval(5 s) andreconnectDelay(min, max)(0.5 s and 30 s).- handle(type, payload -> …)
- Runs the handler for every task of that type. Registering a type again replaces its handler. Returns the worker, for chaining.
- handleTask(type, task -> …)
- The same, for handlers that need the whole Task: id(), type(), payload() (a copy), payloadAsString() (UTF-8) and payloadLength().
- fallback(task -> …)
- Runs tasks whose type has no handler. Without one, they are reported FAILED with the reason "no handler for task type …".
- start() / startInBackground()
- Connects and runs tasks until stop(). start() blocks the calling thread; startInBackground() runs the same loop on a new daemon thread and returns it. A worker starts once: a second start() throws IllegalStateException, so create a new worker to start again.
- stop() / close()
- Lets a running task finish and report its result, then disconnects and ends start(). Safe to call from any thread.
- isRunning(), tasksDone(), tasksFailed()
- Whether the worker is running, and the tasks it has reported DONE and FAILED since it started.
import dev.quicx.QuicxWorker;
import java.nio.charset.StandardCharsets;
public class Worker {
public static void main(String[] args) {
QuicxWorker worker = new QuicxWorker("localhost", 16381)
.handle("send_email", payload ->
EmailService.deliver(new String(payload, StandardCharsets.UTF_8)))
.handleTask("resize_image", task ->
Images.resize(task.id(), task.payload()));
Runtime.getRuntime().addShutdownHook(new Thread(worker::stop));
worker.start(); // blocks until stop()
}
}Threading model#
QuicxClientis safe to share between threads. Calls write their frames one at a time on the client’s single connection, and a background daemon thread named quicx-client host:portreads the daemon’s answers and hands each one to the call waiting for it. submit() blocks its caller until the daemon has accepted the task, submitAndWait() until the result or the timeout, and submitAsync() returns at once.
The futures from submitAsync() are completed on that reader thread, so a callback attached with thenAccept or thenApply before the result arrives runs there too. A slow callback holds up every other answer for the same client. Keep callbacks short, or pass your own executor with thenAcceptAsync(callback, executor).
QuicxWorker runs one task at a time, on the thread that called start(), or on the thread startInBackground() creates, named quicx-worker host:port. A second thread per connection only sends heartbeats. To run tasks in parallel, run several workers, in one process or in several: each has its own connection, and the daemon gives every task to one idle worker. A handler shared by several workers is called from several threads, so it has to be thread-safe.
// four workers, four connections, up to four tasks at a time
static QuicxWorker newWorker() {
return new QuicxWorker("localhost", 16381)
.handleTask("resize_image", task -> Images.resize(task.id(), task.payload()));
}
public static void main(String[] args) {
for (int i = 0; i < 3; i++) newWorker().startInBackground();
newWorker().start(); // the fourth keeps main alive
}Error handling#
Everything the library throws is unchecked and extends QuicxException, so the compiler never forces a catch; catch what you can act on:
- QuicxRejectedException
- The daemon answered
MSG_ERROR, for examplequicxd refused: out of memory (QUEUE_FULL).code()gives theErrorCodeandreason()the daemon’s text.isQueueFull()is true when the memory budget is full and nothing less valuable could be evicted; sending again later, or with a higher level, is the right reaction. - QuicxConnectionException
- The daemon could not be reached, or the connection broke before it answered. The task may or may not have been queued.
- QuicxException
- On its own: submitAndWait() got no result within its timeout ("no result within 5000 ms"), or the waiting thread was interrupted. The task is not cancelled; it stays queued until a worker runs it.
- IllegalArgumentException
- Thrown before sending when a task type, payload or level does not fit in a QXP frame (see the limits below).
| code | ErrorCode | meaning |
|---|---|---|
| 0x01 | QUEUE_FULL | The memory budget is full. In answer to a worker's READY: the worker pool is full, and the worker retries after its reconnect delay. |
| 0x02 | INVALID_MESSAGE | The frame could not be parsed. Also a level above 15, or a valued submit sent to quicxd older than 2.1. |
| 0x03 | PAYLOAD_TOO_BIG | The body is larger than the daemon accepts: 1,024 bytes unless it was built with a larger MAX_PAYLOAD. |
| 0x04 | UNKNOWN_TYPE | A message type the daemon does not know. |
| 0x05 | VERSION_MISMATCH | The client and the daemon speak different QXP versions. |
| UNKNOWN | A code this version of the client does not know. |
A full budget is the error a producer should expect and handle. Back off and try again, and stop after a while so a producer cannot spin forever against a daemon with no workers:
static int submitWithRetry(QuicxClient client, String type, String payload, int level)
throws InterruptedException {
long wait = 50;
while (true) {
try {
return client.submit(type, payload, level);
} catch (QuicxRejectedException e) {
if (!e.isQueueFull() || wait > 5_000) throw e; // not a full budget, or waited enough
}
Thread.sleep(wait);
wait *= 2;
}
}Do not retry a QuicxConnectionException the same way unless the task is safe to run twice: the first attempt may have been queued before the connection broke.
Limits and delivery#
The limits come from QXP and are checked by the client before anything is sent: a task type is 1 to 31 bytes of UTF-8; a submit body (one length byte, the type, the payload, and one more byte for the level in a valued submit) is at most 1,024 bytes, so a plain submit with a 10-byte type has room for 1,013 bytes of payload; a level is 0 to 15; and a failure reason is cut to 63 bytes at a character boundary. A daemon built with make MAX_PAYLOAD=N takes bodies up to N (at most 16,320); set maxBody(N) on the client to match.
Delivery is at-most-once. The daemon frees a task as soon as it hands it to a worker, so if that worker dies mid-task, nothing is reported back and a submitAndWait ends with its timeout. For large data, put the data where your workers can read it and send its path or id as the payload. What else Quicx leaves out is listed in Limitations.