From a3711afefa7a520b3de01be3b2367cb830d1fc84 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C3=A9n=C3=A9dikt=20Tran?=
 <10796600+picnixz@users.noreply.github.com>
Date: Thu, 13 Jun 2024 21:03:01 +0200
Subject: [PATCH] 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>
---
 Doc/library/multiprocessing.rst               |  4 +++
 Lib/test/_test_multiprocessing.py             | 26 +++++++++++++++++++
 ...-06-05-12-36-18.gh-issue-120012.f14DbQ.rst |  3 +++
 3 files changed, 33 insertions(+)
 create mode 100644 Misc/NEWS.d/next/Documentation/2024-06-05-12-36-18.gh-issue-120012.f14DbQ.rst

diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
index 49762491bae..426291c5f07 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 301541a666e..4b3a0645cfc 100644
--- a/Lib/test/_test_multiprocessing.py
+++ b/Lib/test/_test_multiprocessing.py
@@ -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()
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 00000000000..2bf0c977b90
--- /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.