Skip to content

Harden Worker task lifecycle cleanup - #1

Merged
zekageri merged 11 commits into
mainfrom
worker-lifecycle-hardening
Jul 27, 2026
Merged

Harden Worker task lifecycle cleanup#1
zekageri merged 11 commits into
mainfrom
worker-lifecycle-hardening

Conversation

@zekageri

Copy link
Copy Markdown
Collaborator

Summary

Makes Worker fully responsible for releasing completed one-shot and recurring jobs. Callers can use once() as fire-and-forget without calling waitFor() or clearFinished() to recover memory.

Root cause

The previous lifecycle published createdWithCaps after task creation. A fast task could start before that write and select normal vTaskDelete() even though it was created with a PSRAM stack through xTaskCreatePinnedToCoreWithCaps(). The lifecycle also marked taskExited before FreeRTOS deletion ran, retained completed records and callback captures until caller cleanup, and self-deleted capability tasks through ESP-IDF's temporary cleanup-task path.

Changes

  • resolve immutable task allocation metadata before task creation
  • add one Worker-owned cleanup task and bounded cleanup queue
  • externally delete internal and capability-created tasks with the correct API
  • release callback storage before cleanup handoff
  • automatically remove full active job records after physical task deletion
  • keep only a bounded lightweight completion window for optional waitFor() calls
  • make waitFor() and stopAndWait() complete only after stack and TCB release
  • bound active jobs with maxConcurrentJobs so cleanup queue capacity is guaranteed
  • replace historical diagnostics with current runtime and cleanup-task diagnostics
  • retain clearFinished() only as a deprecated compatibility no-op
  • expand the cleanup sentinel to check captures, internal heap, PSRAM, and task count
  • update examples and documentation for automatic cleanup semantics

Caller impact

Normal fire-and-forget usage requires no cleanup:

worker.once([](WorkerJobContext &) {
    runProbe();
});

waitFor() remains available only when application logic needs synchronization with physical task cleanup.

Validation

  • strict host compile with C++20, -Wall -Wextra -Werror, and -fno-exceptions
  • modified examples compiled against Arduino/FreeRTOS compatibility stubs
  • host FreeRTOS lifecycle simulation across Auto, explicit PSRAM, and Internal stack modes
  • 2,400 fire-and-forget jobs with simulated internal RAM, PSRAM, and task counts returning to baseline
  • AddressSanitizer and UndefinedBehaviorSanitizer pass
  • ThreadSanitizer pass
  • production source audit for forbidden exception/abort usage passes

Hardware verification

The updated TaskCleanupSentinel performs warmed ESP32 heap and task-count checks. Native ESP32-P4 execution is still required before treating the original Core memory leak as fully verified on hardware.

@zekageri
zekageri marked this pull request as ready for review July 27, 2026 09:08
@zekageri
zekageri merged commit 7ca1b79 into main Jul 27, 2026
22 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant