Deploy preview for PR 1214 🛫

Author: pydoc-zh-tw[bot]

pr-preview/pr-1214/_sources/c-api/list.rst.txt

@@ -74,11 +74,25 @@ List Objects
    Like :c:func:`PyList_GetItemRef`, but returns a
    :term:`borrowed reference` instead of a :term:`strong reference`.
 
+   .. note::
+
+      In the :term:`free-threaded build`, the returned
+      :term:`borrowed reference` may become invalid if another thread modifies
+      the list concurrently. Prefer :c:func:`PyList_GetItemRef`, which returns
+      a :term:`strong reference`.
+
 
 .. c:function:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
 
    Similar to :c:func:`PyList_GetItem`, but without error checking.
 
+   .. note::
+
+      In the :term:`free-threaded build`, the returned
+      :term:`borrowed reference` may become invalid if another thread modifies
+      the list concurrently. Prefer :c:func:`PyList_GetItemRef`, which returns
+      a :term:`strong reference`.
+
 
 .. c:function:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)
 
@@ -108,6 +122,14 @@ List Objects
       is being replaced; any reference in *list* at position *i* will be
       leaked.
 
+   .. note::
+
+      In the :term:`free-threaded build`, this macro has no internal
+      synchronization. It is normally only used to fill in new lists where no
+      other thread has a reference to the list. If the list may be shared,
+      use :c:func:`PyList_SetItem` instead, which uses a :term:`per-object
+      lock`.
+
 
 .. c:function:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)
 
@@ -138,6 +160,12 @@ List Objects
    Return ``0`` on success, ``-1`` on failure.  Indexing from the end of the
    list is not supported.
 
+   .. note::
+
+      In the :term:`free-threaded build`, when *itemlist* is a :class:`list`,
+      both *list* and *itemlist* are locked for the duration of the operation.
+      For other iterables (or ``NULL``), only *list* is locked.
+
 
 .. c:function:: int PyList_Extend(PyObject *list, PyObject *iterable)
 
@@ -150,6 +178,14 @@ List Objects
 
    .. versionadded:: 3.13
 
+   .. note::
+
+      In the :term:`free-threaded build`, when *iterable* is a :class:`list`,
+      :class:`set`, :class:`dict`, or dict view, both *list* and *iterable*
+      (or its underlying dict) are locked for the duration of the operation.
+      For other iterables, only *list* is locked; *iterable* may be
+      concurrently modified by another thread.
+
 
 .. c:function:: int PyList_Clear(PyObject *list)
 
@@ -168,6 +204,14 @@ List Objects
    Sort the items of *list* in place.  Return ``0`` on success, ``-1`` on
    failure.  This is equivalent to ``list.sort()``.
 
+   .. note::
+
+      In the :term:`free-threaded build`, element comparison via
+      :meth:`~object.__lt__` can execute arbitrary Python code, during which
+      the :term:`per-object lock` may be temporarily released. For built-in
+      types (:class:`str`, :class:`int`, :class:`float`), the lock is not
+      released during comparison.
+
 
 .. c:function:: int PyList_Reverse(PyObject *list)
 

pr-preview/pr-1214/_sources/c-api/typeobj.rst.txt

@@ -3055,6 +3055,24 @@ Buffer Object Structures
 
    (5) Return ``0``.
 
+   **Thread safety:**
+
+   In the :term:`free-threaded build`, implementations must ensure:
+
+   * The export counter increment in step (3) is atomic.
+
+   * The underlying buffer data remains valid and at a stable memory
+     location for the lifetime of all exports.
+
+   * For objects that support resizing or reallocation (such as
+     :class:`bytearray`), the export counter is checked atomically before
+     such operations, and :exc:`BufferError` is raised if exports exist.
+
+   * The function is safe to call concurrently from multiple threads.
+
+   See also :ref:`thread-safety-memoryview` for the Python-level
+   thread safety guarantees of :class:`memoryview` objects.
+
    If *exporter* is part of a chain or tree of buffer providers, two main
    schemes can be used:
 
@@ -3100,6 +3118,16 @@ Buffer Object Structures
 
    (2) If the counter is ``0``, free all memory associated with *view*.
 
+   **Thread safety:**
+
+   In the :term:`free-threaded build`:
+
+   * The export counter decrement in step (1) must be atomic.
+
+   * Resource cleanup when the counter reaches zero must be done atomically,
+     as the final release may race with concurrent releases from other
+     threads and dellocation must only happen once.
+
    The exporter MUST use the :c:member:`~Py_buffer.internal` field to keep
    track of buffer-specific resources. This field is guaranteed to remain
    constant, while a consumer MAY pass a copy of the original buffer as the

pr-preview/pr-1214/_sources/library/stdtypes.rst.txt

@@ -5009,6 +5009,9 @@ copying.
 
       .. versionadded:: 3.3
 
+For information on the thread safety of :class:`memoryview` objects in
+the :term:`free-threaded build`, see :ref:`thread-safety-memoryview`.
+
 
 .. _types-set:
 

pr-preview/pr-1214/_sources/library/threadsafety.rst.txt

@@ -548,3 +548,59 @@ Thread safety for bytearray objects
 
    Consider external synchronization when sharing :class:`bytearray` instances
    across threads.  See :ref:`freethreading-python-howto` for more information.
+
+
+.. _thread-safety-memoryview:
+
+Thread safety for memoryview objects
+====================================
+
+:class:`memoryview` objects provide access to the internal data of an
+underlying object without copying. Thread safety depends on both the
+memoryview itself and the underlying buffer exporter.
+
+The memoryview implementation uses atomic operations to track its own
+exports in the :term:`free-threaded build`. Creating and
+releasing a memoryview are thread-safe. Attribute access (e.g.,
+:attr:`~memoryview.shape`, :attr:`~memoryview.format`) reads fields that
+are immutable for the lifetime of the memoryview, so concurrent reads
+are safe as long as the memoryview has not been released.
+
+However, the actual data accessed through the memoryview is owned by the
+underlying object. Concurrent access to this data is only safe if the
+underlying object supports it:
+
+* For immutable objects like :class:`bytes`, concurrent reads through
+  multiple memoryviews are safe.
+
+* For mutable objects like :class:`bytearray`, reading and writing the
+  same memory region from multiple threads without external
+  synchronization is not safe and may result in data corruption.
+  Note that even read-only memoryviews of mutable objects do not
+  prevent data races if the underlying object is modified from
+  another thread.
+
+.. code-block::
+   :class: bad
+
+   # NOT safe: concurrent writes to the same buffer
+   data = bytearray(1000)
+   view = memoryview(data)
+   # Thread 1: view[0:500] = b'x' * 500
+   # Thread 2: view[0:500] = b'y' * 500
+
+.. code-block::
+   :class: good
+
+   # Safe: use a lock for concurrent access
+   import threading
+   lock = threading.Lock()
+   data = bytearray(1000)
+   view = memoryview(data)
+
+   with lock:
+       view[0:500] = b'x' * 500
+
+Resizing or reallocating the underlying object (such as calling
+:meth:`bytearray.resize`) while a memoryview is exported raises
+:exc:`BufferError`. This is enforced regardless of threading.

pr-preview/pr-1214/_sources/reference/datamodel.rst.txt

@@ -3640,12 +3640,25 @@ implement the protocol in Python.
    provides a convenient way to interpret the flags. The method must return
    a :class:`memoryview` object.
 
+   **Thread safety:** In :term:`free-threaded <free threading>` Python,
+   implementations must manage any internal export counter using atomic
+   operations. The method must be safe to call concurrently from multiple
+   threads, and the returned buffer's underlying data must remain valid
+   until the corresponding :meth:`~object.__release_buffer__` call
+   completes. See :ref:`thread-safety-memoryview` for details.
+
 .. method:: object.__release_buffer__(self, buffer)
 
    Called when a buffer is no longer needed. The *buffer* argument is a
    :class:`memoryview` object that was previously returned by
    :meth:`~object.__buffer__`. The method must release any resources associated
    with the buffer. This method should return ``None``.
+
+   **Thread safety:** In :term:`free-threaded <free threading>` Python,
+   any export counter decrement must use atomic operations. Resource
+   cleanup must be thread-safe, as the final release may race with
+   concurrent releases from other threads.
+
    Buffer objects that do not need to perform any cleanup are not required
    to implement this method.
 

pr-preview/pr-1214/about.html

@@ -356,7 +356,7 @@ <h3>導航</h3>
 <a href="https://www.python.org/psf/donations/">敬請捐贈。</a>
 <br>
     <br>
-      最後更新於 3月 18, 2026 (00:27 UTC)。
+      最後更新於 3月 19, 2026 (00:29 UTC)。
 
       <a href="/bugs.html">發現 bug</a>？
 

pr-preview/pr-1214/bugs.html

@@ -393,7 +393,7 @@ <h3>導航</h3>
 <a href="https://www.python.org/psf/donations/">敬請捐贈。</a>
 <br>
     <br>
-      最後更新於 3月 18, 2026 (00:27 UTC)。
+      最後更新於 3月 19, 2026 (00:29 UTC)。
 
       <a href="/bugs.html">發現 bug</a>？
 

pr-preview/pr-1214/c-api/abstract.html

@@ -365,7 +365,7 @@ <h3>導航</h3>
 <a href="https://www.python.org/psf/donations/">敬請捐贈。</a>
 <br>
     <br>
-      最後更新於 3月 18, 2026 (00:27 UTC)。
+      最後更新於 3月 19, 2026 (00:29 UTC)。
 
       <a href="/bugs.html">發現 bug</a>？
 

pr-preview/pr-1214/c-api/allocation.html

@@ -574,7 +574,7 @@ <h3>導航</h3>
 <a href="https://www.python.org/psf/donations/">敬請捐贈。</a>
 <br>
     <br>
-      最後更新於 3月 18, 2026 (00:27 UTC)。
+      最後更新於 3月 19, 2026 (00:29 UTC)。
 
       <a href="/bugs.html">發現 bug</a>？
 

pr-preview/pr-1214/c-api/apiabiversion.html

@@ -514,7 +514,7 @@ <h3>導航</h3>
 <a href="https://www.python.org/psf/donations/">敬請捐贈。</a>
 <br>
     <br>
-      最後更新於 3月 18, 2026 (00:27 UTC)。
+      最後更新於 3月 19, 2026 (00:29 UTC)。
 
       <a href="/bugs.html">發現 bug</a>？