Apply review comments

Author: ndgrigorian

mkl/_mkl_memory.pyx

@@ -163,6 +163,19 @@ cdef class MKLMemory:
             address alignment of the allocation in bytes. Expected to be a
             power of two and to not exceed ``INT_MAX``. Defaults to the
             alignment of ``other`` in the copy form, and to `64` otherwise.
+
+    Exported buffers and the copy constructor keep :meth:`realloc` from moving
+    the allocation while they use it, but :meth:`tobytes`, :attr:`nbytes`,
+    :attr:`_pointer`, ``len()`` and ``repr()`` read it without doing so. Under
+    the GIL none of these can overlap a resize. On a free-threaded build, when
+    another thread can reach the object during a resize (see :meth:`realloc`),
+    they may read freed memory, or a pointer and a size that do not belong
+    together; as with :meth:`realloc`, arranging exclusive access is the
+    caller's responsibility.
+
+    Pickling preserves the content, the alignment, the subclass and the
+    instance ``__dict__``, but not attributes a subclass stores in
+    ``__slots__``.
     """
     cdef void *_memory_ptr
     cdef Py_ssize_t _nbytes
@@ -390,6 +403,9 @@ cdef class MKLMemory:
     def tobytes(self):
         """
         Constructs bytes object populated with copy of this allocation.
+
+        The copy does not hold the allocation in place, so it must not overlap
+        a :meth:`realloc` from another thread.
         """
         cdef char* data_ptr = <char*>self._memory_ptr
         return data_ptr[:self._nbytes]
@@ -433,4 +449,5 @@ cdef class MKLMemory:
         else:
             args = (self.tobytes(), self._alignment, cls)
 
+        # attributes held in __slots__ of a subclass are not carried over
         return (_mkl_memory_from_bytes, args, getattr(self, "__dict__", None))

mkl/tests/test_mkl_memory.py

@@ -366,12 +366,41 @@ def test_realloc_preserves_alignment(alignment):
 
 def test_realloc_refcheck_shared():
     mem = mkl.MKLMemory(1024)
+    # enough references that no Python version can call this unique
+    aliases = [mem] * 3  # noqa: F841
+    with pytest.raises(ValueError, match="referenced by other objects"):
+        mem.realloc(2048)
+    assert mem.nbytes == 1024
+    del aliases
+
+
+@pytest.mark.skipif(
+    sys.version_info < (3, 14),
+    reason="needs PyUnstable_Object_IsUniquelyReferenced",
+)
+def test_realloc_refcheck_may_be_shared():
+    mem = mkl.MKLMemory(1024)
+    # `mem` is loaded as a borrowed reference, so the refcount during the call
+    # is exactly 2, which is ambiguous
     alias = mem  # noqa: F841
-    with pytest.raises(ValueError, match="referenced by"):
+    with pytest.raises(ValueError, match="may be referenced by another object"):
         mem.realloc(2048)
+    assert mem.nbytes == 1024
     del alias
 
 
+@pytest.mark.skipif(
+    sys.version_info < (3, 14),
+    reason="needs PyUnstable_Object_IsUniquelyReferenced",
+)
+def test_realloc_uniquely_referenced():
+    # a bare local is loaded as a borrowed reference, so during the call it is
+    # uniquely referenced and the resize is allowed
+    mem = mkl.MKLMemory(1024)
+    mem.realloc(2048)
+    assert mem.nbytes == 2048
+
+
 def test_realloc_refcheck_false_allows_shared():
     mem = mkl.MKLMemory(1024)
     mv = memoryview(mem)