preempt_queue.h File Reference

User-configurable preempting work queues + high-priority processing tasks (DETWS_ENABLE_PREEMPT_QUEUE) - the v5 real-time ingest primitive. More...

#include "ServerConfig.h"

Go to the source code of this file.

Detailed Description

User-configurable preempting work queues + high-priority processing tasks (DETWS_ENABLE_PREEMPT_QUEUE) - the v5 real-time ingest primitive.

Fixed-capacity queues, each feeding one dedicated, core-pinned task. A producer posts a fixed-size item; the scheduler preempts the lower-priority producer the instant the item lands so it is processed immediately instead of on the next tick. Producers post from a task (back or front, with a wait timeout) or from an ISR (interrupt-safe, with an immediate context-switch request). Each processing task pops items in order and hands each to a user handler.

Named lanes. There are several queues, addressed by detws_pq_lane:

• detws_pq_lane::DETWS_PQ_LANE_USER - the single lane exposed to the application. The no-lane detws_pq_* API drives it (so existing user code is unchanged). Lowest priority.
• detws_pq_lane::DETWS_PQ_LANE_DMA / _FORWARD / _DEVICE - internal lanes for the library's own real-time work (DMA peripheral transfers, interface forwarding, device access). They run above the user lane (base DETWS_PQ_INTERNAL_PRIORITY, DMA highest), so internal ingest always preempts user work; and below the lwIP tcpip / WiFi tasks so networking is never starved.

This is the single normalized pipe for "hardware event -> process now": a DMA-complete / GPIO / bus ISR posts a descriptor onto its lane, the lane's task drains it. Zero-heap queue storage (static, compile-time DETWS_PQ_DEPTH x DETWS_PQ_ITEM_SIZE per lane; a task's stack is created only when its lane starts, so unused lanes cost only their queue storage), fail-closed on a full queue, no hot-path locks - so latency stays bounded.

Host builds have no FreeRTOS task: posts enqueue into the same fixed per-lane ring and detws_pq_drain[_lane]() runs the handler over what is queued, so the logic is host-testable and behaves identically to the device's draining task.

Author

Douglas Quigg (dstroy0)

Date

2026

Definition in file preempt_queue.h.