pythongh-128182: Add per-object memory access synchronization to ctypes (pythonGH-128490)

Author: ZeroIntensity

Doc/library/ctypes.rst

@@ -870,6 +870,36 @@ invalid non-\ ``NULL`` pointers would crash Python)::
    ValueError: NULL pointer access
    >>>
 
+.. _ctypes-thread-safety:
+
+Thread safety without the GIL
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In Python 3.13, the :term:`GIL` may be disabled on :term:`experimental free threaded <free threading>` builds.
+In ctypes, reads and writes to a single object concurrently is safe, but not across multiple objects:
+
+   .. code-block:: pycon
+
+      >>> number = c_int(42)
+      >>> pointer_a = pointer(number)
+      >>> pointer_b = pointer(number)
+
+In the above, it's only safe for one object to read and write to the address at once if the GIL is disabled.
+So, ``pointer_a`` can be shared and written to across multiple threads, but only if ``pointer_b``
+is not also attempting to do the same. If this is an issue, consider using a :class:`threading.Lock`
+to synchronize access to memory:
+
+   .. code-block:: pycon
+
+      >>> import threading
+      >>> lock = threading.Lock()
+      >>> # Thread 1
+      >>> with lock:
+      ...    pointer_a.contents = 24
+      >>> # Thread 2
+      >>> with lock:
+      ...    pointer_b.contents = 42
+
 
 .. _ctypes-type-conversions:
 

Lib/test/test_ctypes/test_arrays.py

@@ -5,7 +5,7 @@
                     create_string_buffer, create_unicode_buffer,
                     c_char, c_wchar, c_byte, c_ubyte, c_short, c_ushort, c_int, c_uint,
                     c_long, c_ulonglong, c_float, c_double, c_longdouble)
-from test.support import bigmemtest, _2G
+from test.support import bigmemtest, _2G, threading_helper, Py_GIL_DISABLED
 from ._support import (_CData, PyCArrayType, Py_TPFLAGS_DISALLOW_INSTANTIATION,
                        Py_TPFLAGS_IMMUTABLETYPE)
 
@@ -267,6 +267,26 @@ def test_bpo36504_signed_int_overflow(self):
     def test_large_array(self, size):
         c_char * size
 
+    @threading_helper.requires_working_threading()
+    @unittest.skipUnless(Py_GIL_DISABLED, "only meaningful if the GIL is disabled")
+    def test_thread_safety(self):
+        from threading import Thread
+
+        buffer = (ctypes.c_char_p * 10)()
+
+        def run():
+            for i in range(100):
+                buffer.value = b"hello"
+                buffer[0] = b"j"
+
+        with threading_helper.catch_threading_exception() as cm:
+            threads = (Thread(target=run) for _ in range(25))
+            with threading_helper.start_threads(threads):
+                pass
+
+            if cm.exc_value:
+                raise cm.exc_value
+
 
 if __name__ == '__main__':
     unittest.main()

Misc/NEWS.d/next/Library/2025-01-04-11-32-46.gh-issue-128182.SJ2Zsa.rst

@@ -0,0 +1,2 @@
+Fix crash when using :mod:`ctypes` pointers concurrently on the :term:`free
+threaded <free threading>` build.