Skip to content

Commit 11dd68a

Browse files
ishymkosokoliva
andauthored
docs: clarify EventQueue usage (a2aproject#1066)
Fix the comment left from the previous version. Fixes a2aproject#1064. Co-authored-by: Iva Sokolaj <102302011+sokoliva@users.noreply.github.com>
1 parent 3c2559c commit 11dd68a

1 file changed

Lines changed: 19 additions & 28 deletions

File tree

‎src/a2a/server/events/event_queue.py‎

Lines changed: 19 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import asyncio
22
import logging
33
import sys
4+
import warnings
45

56
from abc import ABC, abstractmethod
67
from types import TracebackType
@@ -48,38 +49,28 @@ def _create_async_queue(maxsize: int = 0) -> AsyncQueue[Any]:
4849

4950

5051
class EventQueue(ABC):
51-
"""Base class and factory for EventQueueSource.
52-
53-
EventQueue provides an abstraction for a queue of events that can be tapped
54-
by multiple consumers.
55-
EventQueue maintain main queue and source and maintain child queues in sync.
56-
GUARANTEE: All sinks (including the default one) will receive events in the exact same order.
57-
58-
WARNING (Concurrency): All events from all sinks (both the default queue and any
59-
tapped child queues) must be regularly consumed and marked as done. If any single
60-
consumer stops processing and its queue reaches capacity, it can block the event
61-
dispatcher and stall the entire system, causing a widespread deadlock.
62-
63-
WARNING (Memory Leak): Event queues spawn background tasks. To prevent memory
64-
and task leaks, all queue objects (both source and sinks) MUST be explicitly
65-
closed via `await queue.close()` or by using the async context manager (`async with queue:`).
66-
Child queues are automatically closed when parent queue is closed, but you
67-
should still close them explicitly to prevent queues from reaching capacity by
68-
unconsumed events.
69-
70-
Typical usage:
71-
queue = EventQueue()
72-
child_queue1 = await queue.tap()
73-
child_queue2 = await queue.tap()
74-
75-
async for event in child_queue1:
76-
do_some_work(event)
77-
child_queue1.task_done()
52+
"""Producer-side interface passed to `AgentExecutor.execute`/`cancel`.
53+
54+
Exposes only `enqueue_event`. The consumer is framework-managed
55+
and not part of the public surface.
56+
57+
Default request handlers construct the queue and pass it in; executors
58+
should accept it and not construct one. To run an executor outside the
59+
framework, write a custom subclass or use `EventQueueLegacy` (deprecated,
60+
will be removed in a future release).
7861
"""
7962

8063
def __new__(cls, *args: Any, **kwargs: Any) -> Self:
81-
"""Redirects instantiation to EventQueueLegacy for backwards compatibility."""
64+
"""Deprecated: redirects bare `EventQueue(...)` to `EventQueueLegacy(...)`."""
8265
if cls is EventQueue:
66+
warnings.warn(
67+
'EventQueue is an abstract interface; instantiating it '
68+
'directly is deprecated. The redirect to EventQueueLegacy '
69+
'(and EventQueueLegacy itself) will be removed in a future '
70+
'release.',
71+
DeprecationWarning,
72+
stacklevel=2,
73+
)
8374
instance = EventQueueLegacy.__new__(EventQueueLegacy)
8475
EventQueueLegacy.__init__(instance, *args, **kwargs)
8576
return cast('Self', instance)

0 commit comments

Comments
 (0)