|
1 | 1 | import asyncio |
2 | 2 | import logging |
3 | 3 | import sys |
| 4 | +import warnings |
4 | 5 |
|
5 | 6 | from abc import ABC, abstractmethod |
6 | 7 | from types import TracebackType |
@@ -48,38 +49,28 @@ def _create_async_queue(maxsize: int = 0) -> AsyncQueue[Any]: |
48 | 49 |
|
49 | 50 |
|
50 | 51 | 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). |
78 | 61 | """ |
79 | 62 |
|
80 | 63 | def __new__(cls, *args: Any, **kwargs: Any) -> Self: |
81 | | - """Redirects instantiation to EventQueueLegacy for backwards compatibility.""" |
| 64 | + """Deprecated: redirects bare `EventQueue(...)` to `EventQueueLegacy(...)`.""" |
82 | 65 | 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 | + ) |
83 | 74 | instance = EventQueueLegacy.__new__(EventQueueLegacy) |
84 | 75 | EventQueueLegacy.__init__(instance, *args, **kwargs) |
85 | 76 | return cast('Self', instance) |
|
0 commit comments