From 358c8626d7ec4c607217d64f3dbcd964715edc9f Mon Sep 17 00:00:00 2001 From: Andrew Svetlov Date: Fri, 13 Dec 2024 13:23:53 +0100 Subject: [PATCH] wording --- CHANGES.rst | 11 ++++++++++- janus/__init__.py | 15 ++++++++++++--- 2 files changed, 22 insertions(+), 4 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index a75d8ff..1b20d5b 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -16,7 +16,16 @@ Changes 2.0.0 (2024-12-XX) ------------------ -- Implement .shutdown() for both sync and async APIs #720 +- Implement .shutdown(immediate=False) for both sync and async APIs #720 + + The change is not fully backward compatible: + + 1. If the queue is closed, ``janus.AsyncQueueShutDown`` and + ``janus.SyncQueueShutDown`` exceptions are raised instead of ``RuntimeError``. + + 2. Both sync and async ``.task_done()`` and ``.join()`` don't raise any exception + on queue shutdown/closing anymore; it is compatible with shutdown behavior + of stdlib sync and async queues. 1.2.0 (2024-12-12) diff --git a/janus/__init__.py b/janus/__init__.py index a783564..bc1d7b4 100644 --- a/janus/__init__.py +++ b/janus/__init__.py @@ -139,7 +139,7 @@ def _get_loop(self) -> asyncio.AbstractEventLoop: return loop def shutdown(self, immediate: bool = False) -> None: - """Shut-down the queue, making queue gets and puts raise ShutDown. + """Shut-down the queue, making queue gets and puts raise an exception. By default, gets will only raise once the queue is empty. Set 'immediate' to True to make gets raise immediately instead. @@ -147,6 +147,9 @@ def shutdown(self, immediate: bool = False) -> None: All blocked callers of put() and get() will be unblocked. If 'immediate', a task is marked as done for each item remaining in the queue, which may unblock callers of join(). + + The raise exception is SyncQueueShutDown for sync api and AsyncQueueShutDown + for async one. """ with self._sync_mutex: self._is_shutdown = True @@ -467,7 +470,7 @@ def get_nowait(self) -> T: return self.get(block=False) def shutdown(self, immediate: bool = False) -> None: - """Shut-down the queue, making queue gets and puts raise ShutDown. + """Shut-down the queue, making queue gets and puts raise an exception. By default, gets will only raise once the queue is empty. Set 'immediate' to True to make gets raise immediately instead. @@ -475,6 +478,9 @@ def shutdown(self, immediate: bool = False) -> None: All blocked callers of put() and get() will be unblocked. If 'immediate', a task is marked as done for each item remaining in the queue, which may unblock callers of join(). + + The raise exception is SyncQueueShutDown for sync api and AsyncQueueShutDown + for async one. """ self._parent.shutdown(immediate) @@ -675,7 +681,7 @@ async def join(self) -> None: parent._async_tasks_done_waiting -= 1 def shutdown(self, immediate: bool = False) -> None: - """Shut-down the queue, making queue gets and puts raise ShutDown. + """Shut-down the queue, making queue gets and puts raise an exception. By default, gets will only raise once the queue is empty. Set 'immediate' to True to make gets raise immediately instead. @@ -683,6 +689,9 @@ def shutdown(self, immediate: bool = False) -> None: All blocked callers of put() and get() will be unblocked. If 'immediate', a task is marked as done for each item remaining in the queue, which may unblock callers of join(). + + The raise exception is SyncQueueShutDown for sync api and AsyncQueueShutDown + for async one. """ self._parent.shutdown(immediate)