# KRN-WQ - Work Queues and Delayed Work

Group `KRN-WQ`. Design: `docs/specs/SPEC-006-notifications-and-work-queues.md` §4, §5. Related groups: KRN-NOTIF (the `K_WORK` bit), KRN-TIM (delayed work is a timer; timer callbacks are work items), KRN-THR (the queue's thread), KRN-SYNC (mutex ownership across handlers).

KRN-WQ-001 to 004 originate in `docs/architecture/03-kernel-architecture.md` §6.2. All are restated here as the authoritative copy. New requirements start at 005.

---

## Requirements

### KRN-WQ-001  Intrusive, static, ISR-safe submit
**Statement.** Work items shall be intrusive and statically allocatable; submission shall be ISR-safe and O(1).
**Rationale.** A bottom half is submitted from interrupts; it must cost one push and one bit set.
**Status.** Accepted 2026-10-07
**Verification.** Test: `wq/submit_from_isr`; Analysis: no allocation and no list walk in `emb_work_submit`.
**Trace.** SPEC-006 §4.3

### KRN-WQ-002  FIFO per queue in thread context
**Statement.** Work executes in FIFO order per queue in thread context.
**Rationale.** Deterministic order; handlers may use thread-only API.
**Status.** Accepted 2026-10-07
**Verification.** Test: `wq/fifo_order`, `wq/handler_may_block`.
**Trace.** SPEC-006 §4.3

### KRN-WQ-003  Delayed work over software timers
**Statement.** Delayed work shall be implemented over software timers, not a separate timing mechanism.
**Rationale.** One timeout structure (ADR-010); one set of accuracy rules.
**Status.** Accepted 2026-10-07
**Verification.** Analysis: `emb_dwork_t` embeds `emb_timer_storage_t`; no other timing code in `kernel/work/`.
**Trace.** SPEC-006 §4.1, §4.3; SPEC-003 §7

### KRN-WQ-004  Cancellation reports the state
**Statement.** Cancellation shall report whether the item was pending, running, or idle.
**Rationale.** The caller must know whether a handler may still run.
**Status.** Accepted 2026-10-07
**Verification.** Test: `wq/cancel_pending`, `wq/cancel_running`, `wq/cancel_idle`.
**Trace.** SPEC-006 §4.3

### KRN-WQ-005  Submit outcomes
**Statement.** Submitting a queued item shall return `EMB_EEXIST` and change nothing; submitting an item running on the same queue shall return `EMB_OK` and re-append it after its handler returns; submitting an item running on another queue shall return `EMB_EBUSY`; an item shall never run concurrently with itself.
**Rationale.** Idempotent submission without lost re-submissions and without handler re-entrancy (Zephyr's v2 rule, R-001 §6).
**Status.** Accepted 2026-10-07
**Verification.** Test: `wq/submit_queued_eexist`, `wq/resubmit_while_running_runs_again`, `wq/submit_other_queue_ebusy`.
**Trace.** SPEC-006 §4.3, §12.5

### KRN-WQ-006  Synchronous cancel and flush
**Statement.** `cancel_sync` shall wait until a running handler has returned; `flush` shall return when every item queued before the call has run; calling either from the queue's own thread shall be misuse.
**Rationale.** Teardown needs a point after which no handler touches the caller's state.
**Status.** Accepted 2026-10-07
**Verification.** Test: `wq/cancel_sync_waits`, `wq/flush`, `misuse/wq_flush_from_handler`.
**Trace.** SPEC-006 §4.3, §6

### KRN-WQ-007  Delayed work scheduling
**Statement.** `dwork_schedule` on a pending item shall return `EMB_EEXIST` and change nothing; `reschedule` shall replace a pending delay; cancel shall stop an armed timer or remove a queued item and report `PENDING` for both; the timer's expiry shall submit the item in O(1) from the expiry path.
**Rationale.** One queue hop per delayed item; deterministic re-arm semantics.
**Status.** Accepted 2026-10-07
**Verification.** Test: `wq/dwork_schedule_pending`, `wq/dwork_reschedule`, `wq/dwork_cancel_states`.
**Trace.** SPEC-006 §4.3, §12.6, §12.7

### KRN-WQ-008  System work queue
**Statement.** With `CONFIG_EMB_SYSTEM_WORKQ` the system work queue shall exist from kernel start at `CONFIG_EMB_SYSTEM_WORKQ_PRIO` with `CONFIG_EMB_SYSTEM_WORKQ_STACK`; it shall be the default queue of software timers; the tiny profile shall default to no system queue.
**Rationale.** Timer callbacks need a thread; the tiny profile cannot afford one by default.
**Status.** Accepted 2026-10-07
**Verification.** Test: `wq/system_queue_exists`; footprint test of the tiny profile without it.
**Trace.** SPEC-006 §4.3, §8; SPEC-003 §7.3; ADR-019

### KRN-WQ-009  Work queue thread
**Statement.** A work queue's thread shall wait on the `K_WORK` notification bit, drain the FIFO one item at a time with the item marked `RUNNING` outside the critical section, and run handlers at the queue's priority.
**Rationale.** Fixes the implementation shape so that latency is the thread's dispatch latency plus the handlers ahead.
**Status.** Accepted 2026-10-07
**Verification.** Analysis: `kernel/work/` review; Test: `wq/latency_measured` with the trace events.
**Trace.** SPEC-006 §4.1, §4.3, §4.4

### KRN-WQ-010  Lifecycle misuse
**Statement.** Destroying a queue with queued or running items, flushing or synchronously cancelling from the queue's own thread, and returning from a handler while owning a mutex shall be misuse per SPEC-001 §5.3.
**Rationale.** Each would leave work or locks in an undefined owner.
**Status.** Accepted 2026-10-07
**Verification.** Test: `misuse/wq_*` in checked and release configurations (TEST-010).
**Trace.** SPEC-006 §6

### KRN-WQ-011  Trace and statistics
**Statement.** Submit, start with submit-to-start latency, end with duration, cancel, and delayed scheduling shall be trace events; maximum FIFO length, worst latency, and longest handler with its address shall be optional statistics per queue.
**Rationale.** Work queue latency is the latency of every timer callback and bottom half.
**Status.** Accepted 2026-10-07
**Verification.** Test: trace decoder; statistics API test.
**Trace.** SPEC-006 §7; OBS-005