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 <greg@krypto.org>
This commit is contained in:
Bénédikt Tran 2024-06-13 21:03:01 +02:00 committed by GitHub
parent 6674c63dc7
commit a3711afefa
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 33 additions and 0 deletions

View File

@ -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.

View File

@ -1332,6 +1332,23 @@ class _TestQueue(BaseTestCase):
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 @@ class TestSimpleQueue(unittest.TestCase):
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()

View File

@ -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.