Add documentation note.

python · encukou · Jan 13, 2025 · Jan 4, 2025 · Jan 4, 2025 · Jan 4, 2025
commit d60f2e237d4f8ee4265c873186e3dbfb6c93a29b
diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst
@@ -870,6 +870,35 @@ 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.::
+
+   >>> 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 :term:`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.::
+
+   >>> import threading
+   >>> lock = threading.Lock()
+   >>> # Thread 1
+   >>> with lock:
+   ...    pointer_a.contents = 24
+   >>> # Thread 2
+   >>> with lock:
+   ...    pointer_b.contents = 42
+
+.. seealso::
+
+    :func:`sys._is_gil_enabled` if you would like to dynamically synchronize your application.
 
 .. _ctypes-type-conversions: