log-foundry 0.10.2.dev28__tar.gz → 0.10.2.dev29__tar.gz

{log_foundry-0.10.2.dev28 → log_foundry-0.10.2.dev29}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: log-foundry
-Version: 0.10.2.dev28
+Version: 0.10.2.dev29
 Summary: Generate logs for your console and JSON events for downstream consumption.
 License-Expression: MIT
 License-File: LICENSE
@@ -254,10 +254,30 @@ drain thread may still be inside its `emit`, and `health().incomplete_swaps` rec
 the sink that is already live is a no-op: no drain, no close. The previous sink **is** closed, so
 do not hand it back to a later call.
 
-The 5 s covers the drain, **not** the previous sink's `close()`, which has no timeout of its own —
-a destination that blocks there blocks `configure()`. `KafkaSink.close()` flushes its producer, so
-an unreachable broker is the case to watch. Configure the sink before the first log where you can;
-that path has no worker to retarget and nothing to close.
+The 5 s covers the **whole** call — both drains and the previous sink's `close()`. `Sink.close()`
+takes no timeout of its own (`KafkaSink.close()` flushes its producer, so an unreachable broker
+blocks it), so that close runs on its own daemon thread and is joined for whatever is left of the
+budget. A hung `close()` therefore costs you the budget, once, and the close carries on in the
+background afterwards.
+
+Nothing is *reported* when that join expires — a slow close is not a failed swap, and a counter
+that could not tell the two apart would be worse than none. What you get instead is a live
+reading: `health().closing_sinks` is how many swapped-out sinks are inside `close()` at the moment
+you ask. Non-zero once is a swap in progress; non-zero every time you look is a destination that
+is not coming back, still holding its resources.
+
+**What happens to that background close when the process exits.** `shutdown()` (which `atexit`
+runs for you) drains and closes the live sink first, then gives any still-running swapped-out close
+a short grace — 2 s, per `shutdown()` call, carved from that call's own timeout — to finish. A
+close that was merely slow completes. One that is genuinely stuck is abandoned there, and **its
+own buffered data is lost**: for a sink whose `close()` *is* its delivery, like
+`KafkaSink.close()` flushing the producer, that is everything it had not yet sent.
+`health().closing_sinks` is the only warning you get, which is why it is worth watching.
+
+The closer runs as a daemon thread deliberately. A non-daemon one is worse: CPython joins
+non-daemon threads **before** running `atexit`, so a single stuck `close()` would stop the exit
+drain from ever running — the live sink never drained, and your own `atexit` handlers never run
+either. The grace is what recovers the slow-close case that the daemon flag alone would lose.
 
 `configure()` is still a startup call. It is not thread-safe, and a span finishing on another
 thread mid-swap may land on either sink.
@@ -801,6 +821,9 @@ if (
     ...  # logs were silently lost — worth an alert
 ```
 
+`closing_sinks` is deliberately not a term here: it is briefly non-zero during a perfectly healthy
+sink swap, so a single reading is not a fault. Watch it over time instead — see the table below.
+
 They tell you different things, and they want different responses:
 
 | Field | Means | What to do |
@@ -812,6 +835,7 @@ They tell you different things, and they want different responses:
 | `sink.failed` | The sink attempted delivery and could not confirm it — abandoned requests, partially-failed batches, responses it could not adjudicate. | Fix the destination. |
 | `retired` + `submitted_after_shutdown` | `shutdown()` was called and the process **kept logging**. Those events are queued where nothing will drain them — total loss, for as long as the process runs. | Use `flush()`, not `shutdown()`, in a process that logs again. This is the serverless mistake below. |
 | `incomplete_swaps` | A late `configure(sink=...)` could not confirm the previous sink was drained. The swap took effect; that sink was left open and some queued events may have gone to the new one. | Investigate the previous sink — it was hung or failing. Configure the sink before the first log where you can. |
+| `closing_sinks` | Swapped-out sinks inside `close()` **right now** — a live gauge, not a counter, and the only field that falls as well as rises. Non-zero on a single read is normal during a swap. | Nothing, unless it stays non-zero. That means a destination is stuck in `close()` and will not release its resources. |
 
 `h.sink` is a `SinkLosses(dropped, failed)` or `None` — `None` when no worker exists yet, or when
 the configured sink reports nothing (`losses()` is optional). Note the two `dropped` fields count
@@ -839,8 +863,8 @@ means every log line since the shutdown has gone nowhere. That state used to rea
 healthy: `stopped_reason` is `None` after a clean shutdown, and the queue simply grows.
 
 Read a snapshot by attribute (`h.dropped`), as above. `Health` is a `NamedTuple` and has gained
-fields over time — a fourth (`stopped_reason`) in `v0.7.0`, and a fifth (`sink`) plus a sixth,
-seventh and eighth (`retired`, `submitted_after_shutdown`, `incomplete_swaps`) not yet in a tagged
+fields over time — a fourth (`stopped_reason`) in `v0.7.0`, and a fifth (`sink`) plus four more
+(`retired`, `submitted_after_shutdown`, `incomplete_swaps`, `closing_sinks`) not yet in a tagged
 release — so unpacking it whole (`queued, dropped, failed = health()`) raises `ValueError`. Every
 field keeps its position when a new one is appended, so attribute and index access stay stable.
 

{log_foundry-0.10.2.dev28 → log_foundry-0.10.2.dev29}/README.md

@@ -218,10 +218,30 @@ drain thread may still be inside its `emit`, and `health().incomplete_swaps` rec
 the sink that is already live is a no-op: no drain, no close. The previous sink **is** closed, so
 do not hand it back to a later call.
 
-The 5 s covers the drain, **not** the previous sink's `close()`, which has no timeout of its own —
-a destination that blocks there blocks `configure()`. `KafkaSink.close()` flushes its producer, so
-an unreachable broker is the case to watch. Configure the sink before the first log where you can;
-that path has no worker to retarget and nothing to close.
+The 5 s covers the **whole** call — both drains and the previous sink's `close()`. `Sink.close()`
+takes no timeout of its own (`KafkaSink.close()` flushes its producer, so an unreachable broker
+blocks it), so that close runs on its own daemon thread and is joined for whatever is left of the
+budget. A hung `close()` therefore costs you the budget, once, and the close carries on in the
+background afterwards.
+
+Nothing is *reported* when that join expires — a slow close is not a failed swap, and a counter
+that could not tell the two apart would be worse than none. What you get instead is a live
+reading: `health().closing_sinks` is how many swapped-out sinks are inside `close()` at the moment
+you ask. Non-zero once is a swap in progress; non-zero every time you look is a destination that
+is not coming back, still holding its resources.
+
+**What happens to that background close when the process exits.** `shutdown()` (which `atexit`
+runs for you) drains and closes the live sink first, then gives any still-running swapped-out close
+a short grace — 2 s, per `shutdown()` call, carved from that call's own timeout — to finish. A
+close that was merely slow completes. One that is genuinely stuck is abandoned there, and **its
+own buffered data is lost**: for a sink whose `close()` *is* its delivery, like
+`KafkaSink.close()` flushing the producer, that is everything it had not yet sent.
+`health().closing_sinks` is the only warning you get, which is why it is worth watching.
+
+The closer runs as a daemon thread deliberately. A non-daemon one is worse: CPython joins
+non-daemon threads **before** running `atexit`, so a single stuck `close()` would stop the exit
+drain from ever running — the live sink never drained, and your own `atexit` handlers never run
+either. The grace is what recovers the slow-close case that the daemon flag alone would lose.
 
 `configure()` is still a startup call. It is not thread-safe, and a span finishing on another
 thread mid-swap may land on either sink.
@@ -765,6 +785,9 @@ if (
     ...  # logs were silently lost — worth an alert
 ```
 
+`closing_sinks` is deliberately not a term here: it is briefly non-zero during a perfectly healthy
+sink swap, so a single reading is not a fault. Watch it over time instead — see the table below.
+
 They tell you different things, and they want different responses:
 
 | Field | Means | What to do |
@@ -776,6 +799,7 @@ They tell you different things, and they want different responses:
 | `sink.failed` | The sink attempted delivery and could not confirm it — abandoned requests, partially-failed batches, responses it could not adjudicate. | Fix the destination. |
 | `retired` + `submitted_after_shutdown` | `shutdown()` was called and the process **kept logging**. Those events are queued where nothing will drain them — total loss, for as long as the process runs. | Use `flush()`, not `shutdown()`, in a process that logs again. This is the serverless mistake below. |
 | `incomplete_swaps` | A late `configure(sink=...)` could not confirm the previous sink was drained. The swap took effect; that sink was left open and some queued events may have gone to the new one. | Investigate the previous sink — it was hung or failing. Configure the sink before the first log where you can. |
+| `closing_sinks` | Swapped-out sinks inside `close()` **right now** — a live gauge, not a counter, and the only field that falls as well as rises. Non-zero on a single read is normal during a swap. | Nothing, unless it stays non-zero. That means a destination is stuck in `close()` and will not release its resources. |
 
 `h.sink` is a `SinkLosses(dropped, failed)` or `None` — `None` when no worker exists yet, or when
 the configured sink reports nothing (`losses()` is optional). Note the two `dropped` fields count
@@ -803,8 +827,8 @@ means every log line since the shutdown has gone nowhere. That state used to rea
 healthy: `stopped_reason` is `None` after a clean shutdown, and the queue simply grows.
 
 Read a snapshot by attribute (`h.dropped`), as above. `Health` is a `NamedTuple` and has gained
-fields over time — a fourth (`stopped_reason`) in `v0.7.0`, and a fifth (`sink`) plus a sixth,
-seventh and eighth (`retired`, `submitted_after_shutdown`, `incomplete_swaps`) not yet in a tagged
+fields over time — a fourth (`stopped_reason`) in `v0.7.0`, and a fifth (`sink`) plus four more
+(`retired`, `submitted_after_shutdown`, `incomplete_swaps`, `closing_sinks`) not yet in a tagged
 release — so unpacking it whole (`queued, dropped, failed = health()`) raises `ValueError`. Every
 field keeps its position when a new one is appended, so attribute and index access stay stable.
 

{log_foundry-0.10.2.dev28 → log_foundry-0.10.2.dev29}/pyproject.toml

@@ -20,7 +20,7 @@ dependencies = [
 ]
 
 # Optional features. Install with: pip install log-foundry[aws]
-version = "0.10.2.dev28"
+version = "0.10.2.dev29"
 
 [project.optional-dependencies]
 aws = ["boto3>=1.43.61"]              # SQSSink, SNSSink, KinesisSink, FirehoseSink

{log_foundry-0.10.2.dev28 → log_foundry-0.10.2.dev29}/src/log_foundry/__init__.py

@@ -70,6 +70,9 @@ def health() -> Health:
 
     ``retired`` alone is not a fault — a process that shuts down and then stops logging is
     doing the right thing, which is why it is paired with the count rather than alerted on.
+    ``closing_sinks`` is deliberately absent for the same kind of reason: it is briefly non-zero
+    during a perfectly healthy sink swap, so alerting on a single reading would fire on correct
+    use. It is a gauge to watch over time, not a term in this test.
 
     Args:
       None.
@@ -81,8 +84,11 @@ def health() -> Health:
       afterwards, which are queued where nothing will drain them — non-zero together, that is
       the ``shutdown()``-per-invocation mistake, and the remedy is :func:`flush`.
       ``incomplete_swaps`` counts late ``configure(sink=...)`` calls whose drain of the
-      previous sink could not be confirmed, leaving that sink open. ``sink`` is the configured
-      sink's own
+      previous sink could not be confirmed, leaving that sink open. ``closing_sinks`` is the
+      odd one out — a live gauge rather than a counter, reporting how many swapped-out sinks
+      are inside ``close()`` right now, so a destination stuck there is visible at all; it
+      falls back to zero on its own, and only a *persistently* non-zero reading is a fault.
+      ``sink`` is the configured sink's own
       :class:`~log_foundry.sinks.base.SinkLosses` — loss the sink absorbed rather than the
       worker (SPEC-026) — and is ``None`` when no worker exists or the sink reports nothing.
       Note ``sink`` describes whichever sink is live now, so a swap takes the previous sink's
@@ -117,7 +123,9 @@ def shutdown(timeout: float | None = DEFAULT_SHUTDOWN_TIMEOUT) -> None:
     (SPEC-030). That pair is the reading that catches the mistake above.
 
     Args:
-      timeout: Seconds bounding the wait for the background thread (SPEC-027 FR-004). ``None``
+      timeout: Seconds bounding the wait for the background thread and, carved from the same
+        budget, a short grace for any sink still closing after a late ``configure(sink=...)``
+        (SPEC-027 FR-004, SPEC-030 FR-003). ``None``
         waits indefinitely, which is what this did unconditionally before and is still
         available on request, but is unsafe anywhere with an execution deadline — ``atexit`` is
         one such place, where a sink blocked in a network call would hold the process open. An

{log_foundry-0.10.2.dev28 → log_foundry-0.10.2.dev29}/src/log_foundry/config.py

@@ -86,10 +86,11 @@ def configure(
     is already live is a no-op: no drain, no close. The previous sink is closed and must not be
     handed back to a later call.
 
-    The *closing* of the previous sink is not bounded, because ``Sink.close`` takes no timeout —
-    a destination that blocks in ``close()`` blocks this call. It is the same gap
-    ``architecture.md`` §13 already records for ``shutdown()``, and it has the same fix, which
-    is a change to the sink contract rather than to this function.
+    The bound covers the whole call, the close included. ``Sink.close`` takes no timeout, so that
+    close runs on its own daemon thread and is joined for what is left of the budget: a
+    destination that hangs in ``close()`` delays this call by the budget and no more, then carries
+    on in the background. An expired join reports nothing, since a slow close and a stuck one
+    cannot be told apart at that moment; ``health().closing_sinks`` reports the live fact instead.
 
     This is still a startup call. It is not thread-safe, and a span finishing on another thread
     during a swap may land on either sink.

{log_foundry-0.10.2.dev28 → log_foundry-0.10.2.dev29}/src/log_foundry/decorator.py

@@ -243,7 +243,8 @@ def _swap_sink(new_sink: Sink, timeout: float | None = DEFAULT_SWAP_TIMEOUT) ->
 
     Args:
       new_sink: The sink already written to the config, to be made the live delivery target.
-      timeout: Seconds bounding the drain of the previous sink.
+      timeout: Seconds bounding the whole swap — both drains and the close of the previous
+        sink share it as one deadline.
 
     Returns:
       None.

{log_foundry-0.10.2.dev28 → log_foundry-0.10.2.dev29}/src/log_foundry/worker.py

@@ -26,6 +26,15 @@ and an unbounded join there is a hung process.
 
 _DROP_WARN_EVERY = 1000
 
+DEFAULT_CLOSER_GRACE = 2.0
+"""Seconds :meth:`Worker.shutdown` gives an outstanding swapped-out close to finish.
+
+Deliberately much smaller than the shutdown budget it is carved from. This is a last chance for
+a close that is *nearly* done, not a second full attempt: it already had the swap's whole budget
+(``DEFAULT_SWAP_TIMEOUT``) before ``shutdown`` was ever called, so one still running here is far
+more likely stuck than slow, and every second spent on it is a second the process does not exit.
+"""
+
 DEFAULT_SWAP_TIMEOUT = 5.0
 """Seconds a late ``configure(sink=...)`` will spend draining the previous sink (FR-003).
 
@@ -100,6 +109,14 @@ class Health(NamedTuple):
         call may have been carried to the new sink instead of the old one, and the old sink was
         left **open** rather than closed, because the drain thread may still be inside its
         ``emit`` — the reasoning SPEC-027 FR-004 applies to an expired ``shutdown()``.
+      closing_sinks: Swapped-out sinks whose ``close()`` is running *at this instant* — a live
+        gauge, not a counter, and the only field here that can fall as well as rise. A close is
+        bounded only in how long ``configure()`` waits for it, so this is how a destination
+        stuck in ``close()`` becomes visible at all. Reading it non-zero once means a swap just
+        happened; reading it non-zero repeatedly means a close is not coming back, and that sink
+        still holds its resources. It is deliberately a live read rather than a count of expired
+        joins: a slow close and a stuck one are indistinguishable at the moment a join expires,
+        and SPEC-028 reverted a design that guessed.
     """
 
     queued: int
@@ -110,6 +127,7 @@ class Health(NamedTuple):
     retired: bool = False
     submitted_after_shutdown: int = 0
     incomplete_swaps: int = 0
+    closing_sinks: int = 0
 
 
 class _FlushMarker:
@@ -203,6 +221,7 @@ class Worker:
         self.stopped_reason: str | None = None
         self.submitted_after_shutdown = 0
         self.incomplete_swaps = 0
+        self._closers: list[threading.Thread] = []
         self._queue: queue.Queue[object] = queue.Queue(maxsize=max_queue)
         self._stop = threading.Event()
         self._shutdown_done = False
@@ -337,6 +356,8 @@ class Worker:
             retired = self._shutdown_done
             submitted_after_shutdown = self.submitted_after_shutdown
             incomplete_swaps = self.incomplete_swaps
+            self._closers = [closer for closer in self._closers if closer.is_alive()]
+            closing_sinks = len(self._closers)
         return Health(
             queued=self._queue.qsize(),
             dropped=dropped,
@@ -346,6 +367,7 @@ class Worker:
             retired=retired,
             submitted_after_shutdown=submitted_after_shutdown,
             incomplete_swaps=incomplete_swaps,
+            closing_sinks=closing_sinks,
         )
 
     def _sink_losses(self) -> SinkLosses | None:
@@ -447,10 +469,9 @@ class Worker:
 
         Args:
           new_sink: The sink every subsequent batch is emitted to.
-          timeout: Seconds bounding both drains — one shared deadline, so a hung sink cannot
-            make ``configure()`` wait for twice the budget. It does **not** bound the closing of
-            the old sink, which has no timeout of its own; see :meth:`_close_swapped_out`.
-            ``None`` waits indefinitely.
+          timeout: Seconds bounding the **whole** call — one deadline shared by both drains and
+            the close of the old sink, so a destination that hangs in any of the three cannot
+            hold ``configure()`` for a multiple of the budget. ``None`` waits indefinitely.
 
         Returns:
           None. The outcome is reported through ``health().incomplete_swaps`` and one stderr
@@ -478,7 +499,8 @@ class Worker:
         if not (drained and self.flush(remaining)):
             self._record_incomplete_swap(timeout)
             return
-        self._close_swapped_out(old)
+        left = None if deadline is None else max(0.0, deadline - time.monotonic())
+        self._close_swapped_out(old, left)
 
     def _record_incomplete_swap(self, timeout: float | None) -> None:
         """Counts a swap whose drain could not be confirmed, then announces it (FR-003).
@@ -507,8 +529,8 @@ class Worker:
             f"queued items may reach the new sink instead",
         )
 
-    def _close_swapped_out(self, sink: Sink) -> None:
-        """Closes a sink the worker no longer delivers to, absorbing a failure.
+    def _close_swapped_out(self, sink: Sink, timeout: float | None) -> None:
+        """Closes a sink the worker no longer delivers to, waiting only for the budget.
 
         This is reached only once both drains have been confirmed, so the *drain thread* is
         provably out of this sink's ``emit``. An orphan-path emitter on an application thread
@@ -517,14 +539,24 @@ class Worker:
         ``emit`` — which is why ``sinks/base.py`` requires ``close()`` to tolerate exactly that
         (SPEC-028 FR-001), and why the sinks holding transport state take their lock in both.
 
-        The close is **not** bounded by the swap's timeout: ``Sink.close`` has no timeout of its
-        own, so bounding it needs an interruptible close — a change to the sink contract, not to
-        this method. Of :meth:`_close_if_owed`'s two reasons for rejecting a threaded close, only
-        the second reaches this site: the daemon killed mid-``commit()`` is an interpreter-exit
-        hazard and a swap runs in a live process, but an expired join still cannot tell a
-        slow-but-successful close from a stuck one, and would report a loss for a swap that
-        completed. A destination whose ``close()`` blocks therefore blocks ``configure()``,
-        recorded in ``architecture.md`` §13 rather than papered over.
+        ``Sink.close`` takes no timeout, so the close is run on its own thread and joined for
+        what is left of the swap's budget. **An expired join decides only who waits** — it moves
+        no counter and writes no line, which is what dissolves SPEC-028's objection that an
+        expired join cannot tell a slow-but-successful close from a stuck one and so reports a
+        loss for closes that completed. What *is* observable is a live fact rather than an
+        inference: ``health().closing_sinks`` counts the closes running at the moment it is read.
+
+        The thread is a **daemon**, and it is :meth:`_join_closers` that makes that safe rather
+        than merely available. A non-daemon thread was tried and is worse on its own: CPython
+        joins non-daemon threads *before* running ``atexit``, so one hung close stops the exit
+        drain from ever running and loses everything buffered in the **live** sink, along with
+        the application's own exit handlers. A daemon alone is also worse on its own, in the
+        opposite case: a close that is slow but *succeeding* is killed at exit, losing whatever
+        it was flushing. ``shutdown`` therefore drains and closes the live sink first, then
+        joins any outstanding closer for what is left of its budget — so a slow close finishes,
+        a hung one costs only the grace, and neither can reach the live sink. What SPEC-028
+        refused to abandon was the sink the worker was *still delivering to*; this one has been
+        fenced out of the delivery path by two confirmed drains.
 
         It is deliberately not :meth:`_close_sink`, which answers a different question — that
         one closes the sink the worker still holds, exactly once, and only after the thread has
@@ -532,6 +564,49 @@ class Worker:
 
         Args:
           sink: The sink that was swapped out.
+          timeout: Seconds to wait for the close before returning and letting it finish on its
+            own. ``None`` waits indefinitely.
+
+        Returns:
+          None.
+
+        Raises:
+          None. ``Thread.start`` raises when the platform will not give the process another
+            thread, and a swap that cannot spawn one must leave the sink open and say so rather
+            than fall back to an inline close — the fallback would reintroduce the unbounded
+            wait this method exists to remove, in the one situation where the process is
+            already under resource pressure.
+        """
+        closer = threading.Thread(
+            target=self._close_detached,
+            args=(sink,),
+            name="log-foundry-sink-close",
+            daemon=True,
+        )
+        try:
+            closer.start()
+        except Exception as exc:
+            _diag.absorbed(
+                "starting the thread that closes a swapped-out sink",
+                exc,
+                "it is left open and may still hold its resources",
+            )
+            return
+        with self._lock:
+            self._closers = [old for old in self._closers if old.is_alive()]
+            self._closers.append(closer)
+        closer.join(timeout)
+
+    def _close_detached(self, sink: Sink) -> None:
+        """Closes a swapped-out sink on its own thread, absorbing a failure.
+
+        The guard is what makes the thread safe to leave unattended: an exception escaping here
+        would reach CPython's thread bootstrap, which prints a full traceback carrying the
+        exception's message — the user data arch §6 keeps out of anything the library says about
+        itself, and the reason :meth:`shutdown` guards its own close.
+
+        Args:
+          sink: The sink to close.
 
         Returns:
           None.
@@ -578,11 +653,13 @@ class Worker:
             a full traceback carrying the exception's message, which arch §6 keeps out of
             anything the library says about itself.
         """
+        deadline = None if timeout is None else time.monotonic() + timeout
         with self._lock:
             first = not self._shutdown_done
             self._shutdown_done = True
         if not first:
             self._close_if_owed()
+            self._join_closers(None if deadline is None else max(0.0, deadline - time.monotonic()))
             return
         self._stop.set()
         try:
@@ -603,6 +680,56 @@ class Worker:
             )
             return
         self._close_if_owed()
+        self._join_closers(None if deadline is None else max(0.0, deadline - time.monotonic()))
+
+    def _join_closers(self, timeout: float | None) -> None:
+        """Gives a swapped-out sink's close its last chance before the process exits.
+
+        This is what makes the daemon closer of :meth:`_close_swapped_out` safe rather than
+        merely available. A daemon is killed wherever it has reached at interpreter exit, so
+        without this a close that was slow but *succeeding* — a ``KafkaSink`` flushing its
+        producer, where the close is the delivery — would lose its buffer, which a non-daemon
+        thread would not have. Measured both ways: daemon alone lost those events, non-daemon
+        alone lost everything in the *live* sink instead, and this join is what takes neither
+        loss.
+
+        **The cap is the mechanism.** The wait is the smaller of ``DEFAULT_CLOSER_GRACE`` and
+        what remains of ``shutdown``'s own budget: capped so a stuck close cannot hold a process
+        at exit for the whole shutdown budget, and carved from that budget so it cannot extend it
+        either. Running after :meth:`_close_if_owed` rather than before it is defence in depth
+        rather than the guarantee — measured, the two orders deliver the live sink identically,
+        because the cap returns control long before anything is at risk. It is still the right
+        order, and pinned by a test: it is what holds if an external deadline kills the process
+        *during* the grace, where the live sink would otherwise be the one left unclosed.
+
+        It runs on the idempotent path too. A first ``shutdown`` that expired on a wedged drain
+        thread returns before ever reaching here, and the ``atexit`` call that follows would
+        otherwise return instantly — denying the grace to a swapped-out close that is healthy and
+        moments from finishing, which is exactly the loss the grace exists to prevent. The closer
+        is independent of the worker thread, so a wedged worker is no reason to abandon it. The
+        expired path itself still skips it, and that costs nothing: the thread join consumed the
+        budget, so the remainder is zero.
+
+        Args:
+          timeout: Seconds remaining in ``shutdown``'s budget, further capped by
+            ``DEFAULT_CLOSER_GRACE`` and shared across every outstanding close. ``None`` takes
+            the cap rather than waiting indefinitely — an unbounded ``shutdown`` is a caller's
+            choice about draining events, not a licence for a stuck close to hold the exit.
+
+        Returns:
+          None.
+
+        Raises:
+          None. A join on a thread that has already finished is a no-op, and one that has not
+            is abandoned at the deadline — which is the daemon's contract, not a failure.
+        """
+        with self._lock:
+            closers = [closer for closer in self._closers if closer.is_alive()]
+            self._closers = closers
+        grace = DEFAULT_CLOSER_GRACE if timeout is None else min(timeout, DEFAULT_CLOSER_GRACE)
+        deadline = time.monotonic() + grace
+        for closer in closers:
+            closer.join(max(0.0, deadline - time.monotonic()))
 
     def _close_if_owed(self) -> None:
         """Closes the sink exactly once, and only once the drain thread has ended.