Module work_handler_pool 

Worker-pool saturation metrics for the shared TCP server (backend side).

These metrics expose queue buildup between work_tx.send() and dispatcher pickup, and permit starvation in the bounded worker pool.

Statics

ENGINE_REQUEST_GAUGE

Requests currently in the engine (worker-pool permits in use). Driven from ActiveTaskGuard, alongside WORK_HANDLER_POOL_ACTIVE_TASKS.

REJECTION_REQUEST_TOTAL

Requests shed because the worker was at capacity: all engine in-flight slots (--engine-request-limit) held AND the overflow queue (--dynamo-request-queue-limit) full.

REQUEST_QUEUE_GAUGE

Requests queued in Dynamo but not yet in the engine. Driven alongside WORK_HANDLER_QUEUE_DEPTH (inc on enqueue, dec on dispatcher recv).

WORK_HANDLER_ENQUEUE_REJECTED_TOTAL

Times enqueuing work failed because the dispatcher channel was closed (receiver gone). A full queue is a rejection, counted by REJECTION_REQUEST_TOTAL, not here.

WORK_HANDLER_PERMIT_WAIT_SECONDS

Time spent waiting to acquire a worker-pool permit. Normal operation is sub-millisecond; saturation pushes p99 into seconds.

WORK_HANDLER_POOL_ACTIVE_TASKS

Current number of active worker-pool tasks (permits in use).

WORK_HANDLER_POOL_CAPACITY

Configured worker-pool capacity (total permits). Static; set once at server init.

WORK_HANDLER_QUEUE_CAPACITY

Configured capacity of the bounded work queue. Static; set once at server init.

WORK_HANDLER_QUEUE_DEPTH

Current items sitting in the bounded mpsc work queue awaiting dispatcher pickup. Incremented on successful work_tx.send() and decremented immediately after work_rx.recv(). Permit-acquire wait is NOT counted here — see WORK_HANDLER_PERMIT_WAIT_SECONDS.

Functions

ensure_work_handler_pool_metrics_registered

Register worker-pool saturation metrics with the given registry. Idempotent.