https://github.com/python/cpython/commit/a3711afefa7a520b3de01be3b2367cb830d1fc84
commit: a3711afefa7a520b3de01be3b2367cb830d1fc84
branch: main
author: Bénédikt Tran <10796600+picn...@users.noreply.github.com>
committer: gpshead <g...@krypto.org>
date: 2024-06-13T19:03:01Z
summary:
gh-120012: clarify the behaviour of `multiprocessing.Queue.empty` on closed
queues. (GH-120102)
* improve doc for `multiprocessing.Queue.empty`
* add tests for checking emptiness of queues
Co-authored-by: Gregory P. Smith <g...@krypto.org>
files:
A Misc/NEWS.d/next/Documentation/2024-06-05-12-36-18.gh-issue-120012.f14DbQ.rst
M Doc/library/multiprocessing.rst
M Lib/test/_test_multiprocessing.py
diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
index 49762491bae5f4..426291c5f0743d 100644
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -837,6 +837,8 @@ For an example of the usage of queues for interprocess
communication see
Return ``True`` if the queue is empty, ``False`` otherwise. Because of
multithreading/multiprocessing semantics, this is not reliable.
+ May raise an :exc:`OSError` on closed queues. (not guaranteed)
+
.. method:: full()
Return ``True`` if the queue is full, ``False`` otherwise. Because of
@@ -940,6 +942,8 @@ For an example of the usage of queues for interprocess
communication see
Return ``True`` if the queue is empty, ``False`` otherwise.
+ Always raises an :exc:`OSError` if the SimpleQueue is closed.
+
.. method:: get()
Remove and return an item from the queue.
diff --git a/Lib/test/_test_multiprocessing.py
b/Lib/test/_test_multiprocessing.py
index 301541a666e140..4b3a0645cfc84a 100644
--- a/Lib/test/_test_multiprocessing.py
+++ b/Lib/test/_test_multiprocessing.py
@@ -1332,6 +1332,23 @@ def _on_queue_feeder_error(e, obj):
self.assertTrue(not_serializable_obj.reduce_was_called)
self.assertTrue(not_serializable_obj.on_queue_feeder_error_was_called)
+ def test_closed_queue_empty_exceptions(self):
+ # Assert that checking the emptiness of an unused closed queue
+ # does not raise an OSError. The rationale is that q.close() is
+ # a no-op upon construction and becomes effective once the queue
+ # has been used (e.g., by calling q.put()).
+ for q in multiprocessing.Queue(), multiprocessing.JoinableQueue():
+ q.close() # this is a no-op since the feeder thread is None
+ q.join_thread() # this is also a no-op
+ self.assertTrue(q.empty())
+
+ for q in multiprocessing.Queue(), multiprocessing.JoinableQueue():
+ q.put('foo') # make sure that the queue is 'used'
+ q.close() # close the feeder thread
+ q.join_thread() # make sure to join the feeder thread
+ with self.assertRaisesRegex(OSError, 'is closed'):
+ q.empty()
+
def test_closed_queue_put_get_exceptions(self):
for q in multiprocessing.Queue(), multiprocessing.JoinableQueue():
q.close()
@@ -5815,6 +5832,15 @@ def _test_empty(cls, queue, child_can_start,
parent_can_continue):
finally:
parent_can_continue.set()
+ def test_empty_exceptions(self):
+ # Assert that checking emptiness of a closed queue raises
+ # an OSError, independently of whether the queue was used
+ # or not. This differs from Queue and JoinableQueue.
+ q = multiprocessing.SimpleQueue()
+ q.close() # close the pipe
+ with self.assertRaisesRegex(OSError, 'is closed'):
+ q.empty()
+
def test_empty(self):
queue = multiprocessing.SimpleQueue()
child_can_start = multiprocessing.Event()
diff --git
a/Misc/NEWS.d/next/Documentation/2024-06-05-12-36-18.gh-issue-120012.f14DbQ.rst
b/Misc/NEWS.d/next/Documentation/2024-06-05-12-36-18.gh-issue-120012.f14DbQ.rst
new file mode 100644
index 00000000000000..2bf0c977b90387
--- /dev/null
+++
b/Misc/NEWS.d/next/Documentation/2024-06-05-12-36-18.gh-issue-120012.f14DbQ.rst
@@ -0,0 +1,3 @@
+Clarify the behaviours of :meth:`multiprocessing.Queue.empty` and
+:meth:`multiprocessing.SimpleQueue.empty` on closed queues.
+Patch by Bénédikt Tran.
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-le...@python.org
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: arch...@mail-archive.com
