strictequiv -> syncobj

ericsnowcurrently · ericsnowcurrently · commit 726e57fc8b83 · 2024-02-15T18:42:20.000-07:00
diff --git a/Lib/test/support/interpreters/queues.py b/Lib/test/support/interpreters/queues.py
@@ -35,15 +35,15 @@ class QueueFull(_queues.QueueFull, queue.Full):
 _SHARED_ONLY = 0
 _PICKLED = 1
 
-def create(maxsize=0, *, strictequiv=False):
+def create(maxsize=0, *, syncobj=False):
     """Return a new cross-interpreter queue.
 
     The queue may be used to pass data safely between interpreters.
 
-    "strictequiv" sets the default for Queue.put()
+    "syncobj" sets the default for Queue.put()
     and Queue.put_nowait().
     """
-    fmt = _SHARED_ONLY if strictequiv else _PICKLED
+    fmt = _SHARED_ONLY if syncobj else _PICKLED
     qid = _queues.create(maxsize, fmt)
     return Queue(qid, _fmt=fmt)
 
@@ -115,41 +115,40 @@ def qsize(self):
         return _queues.get_count(self._id)
 
     def put(self, obj, timeout=None, *,
-            strictequiv=None,
+            syncobj=None,
             _delay=10 / 1000,  # 10 milliseconds
             ):
         """Add the object to the queue.
 
         This blocks while the queue is full.
 
-        If "strictequiv" is None (the default) then it uses the
+        If "syncobj" is None (the default) then it uses the
         queue's default, set with create_queue()..
 
-        If "strictequiv" is false then all objects are supported,
+        If "syncobj" 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.
-
+        If "syncobj" is true then the object must be "shareable".
+        Examples of "shareable" objects include the builtin singletons,
+        str, and memoryview.  One benefit is that such objects are
+        passed through the queue efficiently.
+
+        The key difference, though, is conceptual: the corresponding
+        object returned from Queue.get() will be strictly equivalent
+        to the given obj.  In other words, the two objects will be
+        effectively 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 original 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.
+        actually is.  That's a slightly different and stronger promise
+        than just (initial) equality, which is all "syncobj=False"
+        can promise.
         """
-        if strictequiv is None:
+        if syncobj is None:
             fmt = self._fmt
         else:
-            fmt = _SHARED_ONLY if strictequiv else _PICKLED
+            fmt = _SHARED_ONLY if syncobj else _PICKLED
         if timeout is not None:
             timeout = int(timeout)
             if timeout < 0:
@@ -168,11 +167,11 @@ def put(self, obj, timeout=None, *,
             else:
                 break
 
-    def put_nowait(self, obj, *, strictequiv=None):
-        if strictequiv is None:
+    def put_nowait(self, obj, *, syncobj=None):
+        if syncobj is None:
             fmt = self._fmt
         else:
-            fmt = _SHARED_ONLY if strictequiv else _PICKLED
+            fmt = _SHARED_ONLY if syncobj else _PICKLED
         if fmt is _PICKLED:
             obj = pickle.dumps(obj)
         try:
diff --git a/Lib/test/test_interpreters/test_queues.py b/Lib/test/test_interpreters/test_queues.py
@@ -58,13 +58,13 @@ def test_shareable(self):
 
         with self.subTest('same interpreter'):
             queue2 = queues.create()
-            queue1.put(queue2, strictequiv=True)
+            queue1.put(queue2, syncobj=True)
             queue3 = queue1.get()
             self.assertIs(queue3, queue2)
 
         with self.subTest('from current interpreter'):
             queue4 = queues.create()
-            queue1.put(queue4, strictequiv=True)
+            queue1.put(queue4, syncobj=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, strictequiv=True)
+                queue1.put(queue5, syncobj=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, strictequiv=True)
+        queue.put(None, syncobj=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, strictequiv=True)
+            queue.put(None, syncobj=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, strictequiv=True)
+            queue.put(None, syncobj=True)
         actual.append(queue.qsize())
         queue.get()
         actual.append(queue.qsize())
-        queue.put(None, strictequiv=True)
+        queue.put(None, syncobj=True)
         actual.append(queue.qsize())
         for _ in range(3):
             queue.get()
             actual.append(queue.qsize())
-        queue.put(None, strictequiv=True)
+        queue.put(None, syncobj=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 strictequiv in (True, False):
-            kwds = dict(strictequiv=strictequiv)
-            with self.subTest(f'strictequiv={strictequiv}'):
+        for syncobj in (True, False):
+            kwds = dict(syncobj=syncobj)
+            with self.subTest(f'syncobj={syncobj}'):
                 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 strictequiv in (True, False):
-            kwds = dict(strictequiv=strictequiv)
-            with self.subTest(f'strictequiv={strictequiv}'):
+        for syncobj in (True, False):
+            kwds = dict(syncobj=syncobj)
+            with self.subTest(f'syncobj={syncobj}'):
                 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 strictequiv in (True, False):
-            kwds = dict(strictequiv=strictequiv)
-            with self.subTest(f'strictequiv={strictequiv}'):
+        for syncobj in (True, False):
+            kwds = dict(syncobj=syncobj)
+            with self.subTest(f'syncobj={syncobj}'):
                 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_strictequiv(self):
+    def test_put_syncobj(self):
         for obj in [
             None,
             True,
@@ -210,7 +210,7 @@ def test_put_strictequiv(self):
         ]:
             with self.subTest(repr(obj)):
                 queue = queues.create()
-                queue.put(obj, strictequiv=True)
+                queue.put(obj, syncobj=True)
                 obj2 = queue.get()
                 self.assertEqual(obj2, obj)
 
@@ -221,9 +221,9 @@ def test_put_strictequiv(self):
             with self.subTest(repr(obj)):
                 queue = queues.create()
                 with self.assertRaises(interpreters.NotShareableError):
-                    queue.put(obj, strictequiv=True)
+                    queue.put(obj, syncobj=True)
 
-    def test_put_not_strictequiv(self):
+    def test_put_not_syncobj(self):
         for obj in [
             None,
             True,
@@ -237,7 +237,7 @@ def test_put_not_strictequiv(self):
         ]:
             with self.subTest(repr(obj)):
                 queue = queues.create()
-                queue.put(obj, strictequiv=False)
+                queue.put(obj, syncobj=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_strictequiv(self):
+    def test_put_get_default_syncobj(self):
         expected = list(range(20))
-        queue = queues.create(strictequiv=True)
+        queue = queues.create(syncobj=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_strictequiv(self):
         with self.assertRaises(interpreters.NotShareableError):
             queue.put(obj)
 
-    def test_put_get_default_not_strictequiv(self):
+    def test_put_get_default_not_syncobj(self):
         expected = list(range(20))
-        queue = queues.create(strictequiv=False)
+        queue = queues.create(syncobj=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, strictequiv=True)
+            queue.put(orig, syncobj=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, strictequiv=True)
+        queue1.put(obj1, syncobj=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, strictequiv=True)
+                queue2.put(obj2, syncobj=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, strictequiv=True)
-                queue.put(obj2, strictequiv=True)
+                queue.put(obj1, syncobj=True)
+                queue.put(obj2, syncobj=True)
                 """))
         self.assertEqual(queue.qsize(), 2)
 
@@ -360,12 +360,12 @@ def f():
                     break
                 except queues.QueueEmpty:
                     continue
-            queue2.put(obj, strictequiv=True)
+            queue2.put(obj, syncobj=True)
         t = threading.Thread(target=f)
         t.start()
 
         orig = b'spam'
-        queue1.put(orig, strictequiv=True)
+        queue1.put(orig, syncobj=True)
         obj = queue2.get()
         t.join()
 
