preempt_queue.h File Reference

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

#include "protocore_config.h"

Go to the source code of this file.

Detailed Description

User-configurable preempting work queues + high-priority processing tasks (PROTOCORE_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 protocore_pq_lane:

• PROTOCORE_PQ_LANE_USER - the single lane exposed to the application. The no-lane protocore_pq_* API drives it. Lowest priority.
• PROTOCORE_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 PROTOCORE_PQ_INTERNAL_PRIORITY, DMA highest), so internal ingest always preempts user work; and below the network stack's own 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 PROTOCORE_PQ_DEPTH x PROTOCORE_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.

A build with no task backend posts into the same fixed per-lane ring, and protocore_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.