Configuration
One optional quicx.conf: the port, the memory budget and a switch for every allocator feature. Every key has a measured default, and a typo stops the daemon with the file and line instead of falling back silently.
# quicx.conf: every key is optional; these are the built-in defaults
[server]
port = 16381 # TCP port for producers and workers
[memory]
pool_size = 8M # the whole budget, never exceeded (K, M, G)
[allocator]
reserve = on # last free pages only for sizes that own none
hardening = on # encoded free lists; double frees caught
purge = on # empty pages give memory back after a burst
fullest_first = off # Hoard's idea; no gain on queue traffic
warm_pages = auto # empty pages kept before purging (1/8)
reserve_pages = auto # pages the reserve holds back (1/64)
admission = value # when full: refuse, oldest or valueOn start, the daemon prints what it is running with:
config loaded: /etc/quicx/quicx.conf
quicx v2.1.0 starting
port: 16381
pool: 8388608 bytes, 16 KiB pages given to block sizes on demand
apool: reserve, hardening, purge
pages: 508 for tasks (63 kept warm, 7 reserved), 3 for connections and workers[server]#
- port
- TCP port the daemon binds to, 1–65535. Producers and workers both dial the same port, and the first message they send decides the routing (
MSG_SUBMITvsMSG_READY). Default:16381.
[memory]#
- pool_size
- The whole memory budget, mapped once with
mmapat startup and never grown. Bytes, or with aK,MorGsuffix (1024-based;8MBis refused as ambiguous). Default8M. Three pages of it hold connections and workers, the rest holds tasks; when it is full, newMSG_SUBMITframes getMSG_ERROR 0x01 (queue full).
How many tasks fit#
Every task takes a known amount of memory, so the capacity of a budget can be worked out before the daemon starts. A task is a 64-byte record plus its payload, rounded up to 16 bytes. A 16 KiB page holds as many of those blocks as fit whole. Three pages hold connections and workers, each page has a 32-byte record, and 1/64 of the task pages are kept for a size that has none yet.
block = ceil((64 + payload) / 16) * 16
per page = floor(16384 / block)
task pages = pool / 16 KiB - 3 - (one page of records per 512)
tasks = (task pages - task pages / 64) * per page| pool_size | payload | calculated | measured |
|---|---|---|---|
| 8 MiB | 100 B | 46,593 | 46,593 |
| 8 MiB | 40 B | 73,146 | 73,146 |
| 256 KiB | 48 B | 1,752 | 1,752 |
A worked example: a camera makes 30 frames a second and a model analyses 10, so 20 more wait every second. Each task carries a 48-byte frame reference and takes a 112-byte block. If 64 MB is set aside for waiting frames of about 50 KB, about 1,300 frames can wait. pool_size = 208K holds exactly 1,314 tasks, the queue itself costs 208 KB, and it fills in about 65 seconds. From then on the camera gets ERROR 0x01 and skips frames instead of the device running out of memory.
[allocator]#
Switches for the features of apool v2, each taken from a published allocator and measured on its own. The defaults are the measured best for a task queue; change them to trade capacity, safety or memory against each other.
- reserve = on | off
- With
reserve_pagesor fewer pages free, only a size that owns no page yet may take one, so a flood of one size cannot lock every other size out. Costs about 1.4 % of capacity. - hardening = on | off
- Free-list links are XOR-encoded with a per-pool key; an overwritten link is caught before it is followed and a double free is refused and counted. About 1 ns per task on an Apple M4 Pro, 13 ns on a 2011 Intel i3.
- purge = on | off
- Empty pages are reused newest first; beyond
warm_pagesof them, the oldest gives its memory back to the OS. Off keeps the memory of the biggest burst for the life of the process. - fullest_first = on | off
- Allocate from the fullest page of a size first, so emptier pages drain. Off by default: queue traffic frees in arrival order, so pages drain on their own and the extra bookkeeping only costs time.
- warm_pages = auto | N
- Empty pages kept backed and ready before purging starts.
autois 1/8 of the pages (63 at 8 MiB). Needspurge = on. - reserve_pages = auto | N
- Pages the reserve holds back.
autois 1/64 of the pages (7 at 8 MiB). Needsreserve = on. - admission = refuse | oldest | value
- What a full budget does with a new task.
refuseanswersERROR 0x01.oldestevicts the oldest waiting task.value(default) evicts the oldest task of the lowest value level below the new one, and only when its memory fits the new task: the same block size, or the last block of a page. Tasks sent withMSG_SUBMIT_VALUEDcarry a level from 0 to 15; plain ones are level 8, so with plain SUBMITsvaluebehaves likerefuse. Level 15 is never evicted. Results: Benchmarks.
Upgrading from 1.x#
A 1.x file still loads. Its class = SIZE,PCT lines laid out the old fixed size classes; apool sizes itself, so they are ignored with a note, and pool_size is still read under [allocator]. Nothing about the pool needs tuning per workload any more.