gh-120012: clarify the behaviour of multiprocessing.Queue.empty on closed queues.

Doc/library/multiprocessing.rst

@@ -837,6 +837,10 @@ 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.
 
+      If :meth:`put` or :meth:`put_nowait` has been called previously (i.e.,
+      if the feeder thread has been started) and if the queue is closed, this
+      method raises an :exc:`OSError` instead.
+
    .. method:: full()
 
       Return ``True`` if the queue is full, ``False`` otherwise.  Because of
@@ -940,6 +944,10 @@ For an example of the usage of queues for interprocess communication see
 
       Return ``True`` if the queue is empty, ``False`` otherwise.
 
+      Unlike :meth:`Queue.empty`, if the queue is closed and this
+      method is called, this raises an :exc:`OSError` even if the
+      queue was never used.
+
    .. method:: get()
 
       Remove and return an item from the queue.

Lib/test/_test_multiprocessing.py

@@ -1332,6 +1332,19 @@ 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):
+        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')
+            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 +5828,12 @@ def _test_empty(cls, queue, child_can_start, parent_can_continue):
         finally:
             parent_can_continue.set()
 
+    def test_empty_exceptions(self):
+        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()

Misc/NEWS.d/next/Documentation/2024-06-05-12-36-18.gh-issue-120012.f14DbQ.rst

@@ -0,0 +1,2 @@
+Clarify the behaviour of :meth:`multiprocessing.Queue.empty` on closed
+queues. Patch by Bénédikt Tran.