Skip to content

CONCEPT Cited by 1 source

Explicit teardown on completion

Definition

Explicit teardown on completion is the reliability property where reaching a terminal state of a state machine (e.g. Finished, Cancelled, Failed) automatically and explicitly releases all resources associated with the managed resource — memory buffers, executor threads, intermediate artefacts, scheduler slots, locks — rather than leaving cleanup to run via implicit mechanisms (garbage collection, finalisers, reference counting, or worse, polling and reaping).

Canonical wiki instance: Oxla's 2026-01-27 query manager rewrite. Verbatim: "Cleanup is also explicit now. When a query finishes, the scheduler and executors are torn down cleanly. Finished queries stay finished. Canceled queries are accounted for. Nothing hangs around quietly consuming resources anymore." (Source: sources/2026-01-27-redpanda-engineering-den-query-manager-implementation-demo).

The pathology it fixes

Oxla's pre-rewrite query manager exhibited the failure mode verbatim: "Queries could get stuck in 'finished' or 'executing' while still holding onto resources." — the terminal finished label was reached but the associated resources weren't released. The label and the state-machine reality diverged; from outside, the query was done; internally, executors were still active, memory buffers were still allocated, scheduler slots were still claimed.

This is a resource leak via incomplete state transition — the state was transitioning but the side effects of transitioning weren't firing.

Why explicit matters

"Explicit" here contrasts with several implicit cleanup approaches that can go wrong:

  • Garbage collection: works for memory but not for scheduler slots, thread handles, or external resources (connections, disk files, kernel objects). And GC can be delayed indefinitely under memory pressure.
  • Reference counting / RAII: works when ownership is clean and acyclic, but query executors often form ownership graphs where the scheduler holds executors which hold queries which hold the scheduler — cycles defeat simple refcounting.
  • Finaliser-style cleanup on destruction: fires at an unpredictable time, in an unpredictable order, and can itself fail silently.
  • Poll-and-reap: a background janitor that finds "finished" resources and cleans them up — adds its own race conditions (what if a query is about to transition to finished? what if the janitor is slow?) and adds a heartbeat-style observability surface that itself can fail.

Explicit teardown says: the state-machine transition to a terminal state is the point at which cleanup runs, synchronously, as part of the transition handler. The Finished state is not just a label; it's a behaviour — a cleanup routine.

Composition with state machine

Explicit teardown presumes the state machine is deterministic and the transitions are logged. The three properties compose:

  1. Deterministic state machine: terminal states are enumerated and reachable only via enumerated transitions.
  2. State-transition logging: the moment of transition is observable after the fact.
  3. Explicit teardown on completion: the transition to a terminal state runs the cleanup routine.

Without (1) + (2), teardown is running against an implicit state that may or may not match reality. Together, the three properties produce the guarantee: reaching Finished means the query's resources are released (not should be released, not will eventually be released).

Terminal-state plurality

Most query-lifecycle state machines have multiple terminal states:

  • Finished (normal completion, client got results)
  • Cancelled (client/admin asked to stop)
  • Failed (execution error, timeout, crash)

Explicit teardown applies to all terminal states. Oxla's rewrite makes this explicit: "Finished queries stay finished. Canceled queries are accounted for." — different terminal states, same teardown guarantee.

Scope

This concept generalises beyond query managers to any lifecycle-managed resource:

  • Connection lifecycle: TCP CLOSED state should release kernel buffers + socket descriptor.
  • Workflow lifecycle: Temporal-style workflows need cleanup on Completed / Cancelled / Failed — see concepts/fault-tolerant-long-running-workflow.
  • Request lifecycle: consensus requests transitioning to Completed or Cancelled release their leader leases + held resources — see concepts/request-cancellation.

In each case, the pattern is: terminal state + explicit teardown routine attached to that state's transition handler.

Contrast: the "stuck in finished" anti-pattern

The failure mode Oxla named — "queries could get stuck in 'finished' while still holding onto resources" — is the absence of this concept. The query's state label says it's done; the query's substrate doesn't know that. The "label" and the "behaviour" have diverged because the transition handler for Finished doesn't atomically complete its cleanup work.

Fixing this requires making the transition handler transactional in spirit: either the transition to Finished happens and all the cleanup happens, or neither happens. Reaching Finished is the commit of teardown.

Seen in

Last updated · 470 distilled / 1,213 read