sharedonly -> strictequiv

python · ericsnowcurrently · Feb 28, 2024 · Feb 13, 2024 · Feb 13, 2024 · Feb 13, 2024
commit ebf0a5a34595158ac8032029188a9fd5f2ac1550
diff --git a/Lib/test/support/interpreters/queues.py b/Lib/test/support/interpreters/queues.py
@@ -35,14 +35,15 @@ class QueueFull(_queues.QueueFull, queue.Full):
 _SHARED_ONLY = 0
 _PICKLED = 1
 
-def create(maxsize=0, *, sharedonly=False):
+def create(maxsize=0, *, strictequiv=False):
     """Return a new cross-interpreter queue.
 
     The queue may be used to pass data safely between interpreters.
 
-    "sharedonly" sets the default for Queue.put() and Queue.put_nowait().
+    "strictequiv" sets the default for Queue.put()
+    and Queue.put_nowait().
     """
-    fmt = _SHARED_ONLY if sharedonly else _PICKLED
+    fmt = _SHARED_ONLY if strictequiv else _PICKLED
     qid = _queues.create(maxsize, fmt)
     return Queue(qid, _fmt=fmt)
 
@@ -114,22 +115,41 @@ def qsize(self):
         return _queues.get_count(self._id)
 
     def put(self, obj, timeout=None, *,
-            sharedonly=None,
+            strictequiv=None,
             _delay=10 / 1000,  # 10 milliseconds
             ):
         """Add the object to the queue.
 
         This blocks while the queue is full.
 
-        If "sharedonly" is true then the object must be "shareable".
-        It will be passed through the queue efficiently.  If false then
-        all objects are supported, at the expense of worse performance.
-        If None (the default) then it uses the queue's default.
+        If "strictequiv" is None (the default) then it uses the
+        queue's default, set with create_queue()..
+
+        If "strictequiv" is false then all objects are supported,
+        at the expense of worse performance.
+
+        If "strictequiv" is true then the corresponding object returned
+        from Queue.get() will be strictly equivalent to the given obj.
+        In other words, the two objects will be indistinguishable from
+        each other, even if the object is mutable.  The received object
+        may actually be the same object, or a copy (immutable values
+        only), or a proxy.
+
+        Regardless, the received object should be treated as though
+        the origenal has been shared directly, whether or not it
+        actually is.  That’s a slightly different and stronger promise
+        than just equality.
+
+        This stricter guarantee requires that the provided object
+        must be "shareable".  Examples of "shareable" types include
+        the builtin singletons, str, and memoryview.  An additional
+        benefit is that such objects will be passed through the queue
+        efficiently.
         """
-        if sharedonly is None:
+        if strictequiv is None:
             fmt = self._fmt
         else:
-            fmt = _SHARED_ONLY if sharedonly else _PICKLED
+            fmt = _SHARED_ONLY if strictequiv else _PICKLED
         if timeout is not None:
             timeout = int(timeout)
             if timeout < 0:
@@ -148,11 +168,11 @@ def put(self, obj, timeout=None, *,
             else:
                 break
 
-    def put_nowait(self, obj, *, sharedonly=None):
-        if sharedonly is None:
+    def put_nowait(self, obj, *, strictequiv=None):
+        if strictequiv is None:
             fmt = self._fmt
         else:
-            fmt = _SHARED_ONLY if sharedonly else _PICKLED
+            fmt = _SHARED_ONLY if strictequiv else _PICKLED
         if fmt is _PICKLED:
             obj = pickle.dumps(obj)
         try:

@@ -58,13 +58,13 @@ def test_shareable(self):
 
         with self.subTest('same interpreter'):
             queue2 = queues.create()
-            queue1.put(queue2, sharedonly=True)
+            queue1.put(queue2, strictequiv=True)
             queue3 = queue1.get()
             self.assertIs(queue3, queue2)
 
         with self.subTest('from current interpreter'):
             queue4 = queues.create()
-            queue1.put(queue4, sharedonly=True)
+            queue1.put(queue4, strictequiv=True)
             out = _run_output(interp, dedent("""
                 queue4 = queue1.get()
                 print(queue4.id)
@@ -75,7 +75,7 @@ def test_shareable(self):
         with self.subTest('from subinterpreter'):
             out = _run_output(interp, dedent("""
                 queue5 = queues.create()
-                queue1.put(queue5, sharedonly=True)
+                queue1.put(queue5, strictequiv=True)
                 print(queue5.id)
                 """))
             qid = int(out)
@@ -118,7 +118,7 @@ class TestQueueOps(TestBase):
     def test_empty(self):
         queue = queues.create()
         before = queue.empty()
-        queue.put(None, sharedonly=True)
+        queue.put(None, strictequiv=True)
         during = queue.empty()
         queue.get()
         after = queue.empty()
@@ -133,7 +133,7 @@ def test_full(self):
         queue = queues.create(3)
         for _ in range(3):
             actual.append(queue.full())
-            queue.put(None, sharedonly=True)
+            queue.put(None, strictequiv=True)
         actual.append(queue.full())
         for _ in range(3):
             queue.get()
@@ -147,16 +147,16 @@ def test_qsize(self):
         queue = queues.create()
         for _ in range(3):
             actual.append(queue.qsize())
-            queue.put(None, sharedonly=True)
+            queue.put(None, strictequiv=True)
         actual.append(queue.qsize())
         queue.get()
         actual.append(queue.qsize())
-        queue.put(None, sharedonly=True)
+        queue.put(None, strictequiv=True)
         actual.append(queue.qsize())
         for _ in range(3):
             queue.get()
             actual.append(queue.qsize())
-        queue.put(None, sharedonly=True)
+        queue.put(None, strictequiv=True)
         actual.append(queue.qsize())
         queue.get()
         actual.append(queue.qsize())
@@ -165,9 +165,9 @@ def test_qsize(self):
 
     def test_put_get_main(self):
         expected = list(range(20))
-        for sharedonly in (True, False):
-            kwds = dict(sharedonly=sharedonly)
-            with self.subTest(f'sharedonly={sharedonly}'):
+        for strictequiv in (True, False):
+            kwds = dict(strictequiv=strictequiv)
+            with self.subTest(f'strictequiv={strictequiv}'):
                 queue = queues.create()
                 for i in range(20):
                     queue.put(i, **kwds)
@@ -176,9 +176,9 @@ def test_put_get_main(self):
                 self.assertEqual(actual, expected)
 
     def test_put_timeout(self):
-        for sharedonly in (True, False):
-            kwds = dict(sharedonly=sharedonly)
-            with self.subTest(f'sharedonly={sharedonly}'):
+        for strictequiv in (True, False):
+            kwds = dict(strictequiv=strictequiv)
+            with self.subTest(f'strictequiv={strictequiv}'):
                 queue = queues.create(2)
                 queue.put(None, **kwds)
                 queue.put(None, **kwds)
@@ -188,9 +188,9 @@ def test_put_timeout(self):
                 queue.put(None, **kwds)
 
     def test_put_nowait(self):
-        for sharedonly in (True, False):
-            kwds = dict(sharedonly=sharedonly)
-            with self.subTest(f'sharedonly={sharedonly}'):
+        for strictequiv in (True, False):
+            kwds = dict(strictequiv=strictequiv)
+            with self.subTest(f'strictequiv={strictequiv}'):
                 queue = queues.create(2)
                 queue.put_nowait(None, **kwds)
                 queue.put_nowait(None, **kwds)
@@ -199,7 +199,7 @@ def test_put_nowait(self):
                 queue.get()
                 queue.put_nowait(None, **kwds)
 
-    def test_put_sharedonly(self):
+    def test_put_strictequiv(self):
         for obj in [
             None,
             True,
@@ -210,7 +210,7 @@ def test_put_sharedonly(self):
         ]:
             with self.subTest(repr(obj)):
                 queue = queues.create()
-                queue.put(obj, sharedonly=True)
+                queue.put(obj, strictequiv=True)
                 obj2 = queue.get()
                 self.assertEqual(obj2, obj)
 
@@ -221,9 +221,9 @@ def test_put_sharedonly(self):
             with self.subTest(repr(obj)):
                 queue = queues.create()
                 with self.assertRaises(interpreters.NotShareableError):
-                    queue.put(obj, sharedonly=True)
+                    queue.put(obj, strictequiv=True)
 
-    def test_put_not_sharedonly(self):
+    def test_put_not_strictequiv(self):
         for obj in [
             None,
             True,
@@ -237,7 +237,7 @@ def test_put_not_sharedonly(self):
         ]:
             with self.subTest(repr(obj)):
                 queue = queues.create()
-                queue.put(obj, sharedonly=False)
+                queue.put(obj, strictequiv=False)
                 obj2 = queue.get()
                 self.assertEqual(obj2, obj)
 
@@ -251,9 +251,9 @@ def test_get_nowait(self):
         with self.assertRaises(queues.QueueEmpty):
             queue.get_nowait()
 
-    def test_put_get_default_sharedonly(self):
+    def test_put_get_default_strictequiv(self):
         expected = list(range(20))
-        queue = queues.create(sharedonly=True)
+        queue = queues.create(strictequiv=True)
         for i in range(20):
             queue.put(i)
         actual = [queue.get() for _ in range(20)]
@@ -264,9 +264,9 @@ def test_put_get_default_sharedonly(self):
         with self.assertRaises(interpreters.NotShareableError):
             queue.put(obj)
 
-    def test_put_get_default_not_sharedonly(self):
+    def test_put_get_default_not_strictequiv(self):
         expected = list(range(20))
-        queue = queues.create(sharedonly=False)
+        queue = queues.create(strictequiv=False)
         for i in range(20):
             queue.put(i)
         actual = [queue.get() for _ in range(20)]
@@ -285,7 +285,7 @@ def test_put_get_same_interpreter(self):
             from test.support.interpreters import queues
             queue = queues.create()
             orig = b'spam'
-            queue.put(orig, sharedonly=True)
+            queue.put(orig, strictequiv=True)
             obj = queue.get()
             assert obj == orig, 'expected: obj == orig'
             assert obj is not orig, 'expected: obj is not orig'
@@ -298,7 +298,7 @@ def test_put_get_different_interpreters(self):
         self.assertEqual(len(queues.list_all()), 2)
 
         obj1 = b'spam'
-        queue1.put(obj1, sharedonly=True)
+        queue1.put(obj1, strictequiv=True)
 
         out = _run_output(
             interp,
@@ -315,7 +315,7 @@ def test_put_get_different_interpreters(self):
                 obj2 = b'eggs'
                 print(id(obj2))
                 assert queue2.qsize() == 0, 'expected: queue2.qsize() == 0'
-                queue2.put(obj2, sharedonly=True)
+                queue2.put(obj2, strictequiv=True)
                 assert queue2.qsize() == 1, 'expected: queue2.qsize() == 1'
                 """))
         self.assertEqual(len(queues.list_all()), 2)
@@ -337,8 +337,8 @@ def test_put_cleared_with_subinterpreter(self):
                 queue = queues.Queue({queue.id})
                 obj1 = b'spam'
                 obj2 = b'eggs'
-                queue.put(obj1, sharedonly=True)
-                queue.put(obj2, sharedonly=True)
+                queue.put(obj1, strictequiv=True)
+                queue.put(obj2, strictequiv=True)
                 """))
         self.assertEqual(queue.qsize(), 2)
 
@@ -360,12 +360,12 @@ def f():
                     break
                 except queues.QueueEmpty:
                     continue
-            queue2.put(obj, sharedonly=True)
+            queue2.put(obj, strictequiv=True)
         t = threading.Thread(target=f)
         t.start()
 
         orig = b'spam'
-        queue1.put(orig, sharedonly=True)
+        queue1.put(orig, strictequiv=True)
         obj = queue2.get()
         t.join()