Skip to content

Commit db22865

Browse files
graph: document drain unbounded-wait risk and wait_for workaround
Drain blocks until every queued event has been delivered, so a slow or hung observer can hold the calling process indefinitely. Note this in the drain() docstring with the asyncio.wait_for stop-gap pattern. A spec proposal for a first-class deadline parameter is in flight; this docstring nudge holds until it lands. Also bump the docstring's spec version reference from v0.3.0 to v0.6.0 to match the rest of the file.
1 parent 3d7de3d commit db22865

1 file changed

Lines changed: 10 additions & 1 deletion

File tree

src/openarmature/graph/compiled.py

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -156,14 +156,23 @@ async def drain(self) -> None:
156156
"""Await delivery of every observer event produced by prior
157157
invocations of this graph.
158158
159-
Per spec v0.3.0 §6: callers running in short-lived processes (scripts,
159+
Per spec v0.6.0 §6: callers running in short-lived processes (scripts,
160160
serverless functions, CLIs) MUST use drain to avoid losing observer
161161
events that were dispatched but not yet delivered.
162162
163163
Only events dispatched before this call are awaited; events from
164164
invocations started concurrently with drain may or may not be
165165
included. Subgraph events from active invocations are part of the
166166
parent invocation's worker and are covered automatically.
167+
168+
**Unbounded by design.** Drain blocks until every queued event has
169+
been delivered to every subscribed observer. A slow, hung, or
170+
misbehaving observer can therefore hold drain — and the calling
171+
process — indefinitely. If you need a bounded wait, wrap the call
172+
in `asyncio.wait_for` and accept that events still queued when the
173+
deadline elapses will not be delivered::
174+
175+
await asyncio.wait_for(compiled.drain(), timeout=5.0)
167176
"""
168177
if not self._active_workers:
169178
return

0 commit comments

Comments
 (0)