gh-75459: Doc: C API: Improve object life cycle documentation

.gitattributes

@@ -10,6 +10,7 @@
 *.ico binary
 *.jpg binary
 *.pck binary
+*.pdf binary
 *.png binary
 *.psd binary
 *.tar binary
@@ -67,6 +68,7 @@ PCbuild/readme.txt dos
 **/clinic/*.cpp.h generated
 **/clinic/*.h.h generated
 *_db.h generated
+Doc/c-api/lifecycle.dot.svg generated
 Doc/data/stable_abi.dat generated
 Doc/library/token-list.inc generated
 Include/internal/pycore_ast.h generated

Doc/c-api/allocation.rst

@@ -16,46 +16,128 @@ Allocating Objects on the Heap
 
  Initialize a newly allocated object *op* with its type and initial
  reference. Returns the initialized object. Other fields of the object are
- not affected.
+ not initialized. Despite its name, this function is unrelated to the
+ object's :meth:`~object.__init__` method (:c:member:`~PyTypeObject.tp_init`
+ slot). Specifically, this function does **not** call the object's
+ :meth:`!__init__` method.
+
+ In general, consider this function to be a low-level routine. Use
+ :c:member:`~PyTypeObject.tp_alloc` where possible.
+ For implementing :c:member:`!tp_alloc` for your type, prefer
+ :c:func:`PyType_GenericAlloc` or :c:func:`PyObject_New`.
+
+ .. note::
+
+ This function only initializes the object's memory corresponding to the
+ initial :c:type:`PyObject` structure. It does not zero the rest.
 
 
 .. c:function:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
 
  This does everything :c:func:`PyObject_Init` does, and also initializes the
  length information for a variable-size object.
 
+ .. note::
+
+ This function only initializes some of the object's memory. It does not
+ zero the rest.
+
 
 .. c:macro:: PyObject_New(TYPE, typeobj)
 
- Allocate a new Python object using the C structure type *TYPE*
- and the Python type object *typeobj* (``PyTypeObject*``).
- Fields not defined by the Python object header are not initialized.
- The caller will own the only reference to the object
- (i.e. its reference count will be one).
- The size of the memory allocation is determined from the
- :c:member:`~PyTypeObject.tp_basicsize` field of the type object.
+ Allocates a new Python object using the C structure type *TYPE* and the
+ Python type object *typeobj* (``PyTypeObject*``) by calling
+ :c:func:`PyObject_Malloc` to allocate memory and initializing it like
+ :c:func:`PyObject_Init`. The caller will own the only reference to the
+ object (i.e. its reference count will be one).
+
+ Avoid calling this directly to allocate memory for an object; call the type's
+ :c:member:`~PyTypeObject.tp_alloc` slot instead.
+
+ When populating a type's :c:member:`~PyTypeObject.tp_alloc` slot,
+ :c:func:`PyType_GenericAlloc` is preferred over a custom function that
+ simply calls this macro.
+
+ This macro does not call :c:member:`~PyTypeObject.tp_alloc`,
+ :c:member:`~PyTypeObject.tp_new` (:meth:`~object.__new__`), or
+ :c:member:`~PyTypeObject.tp_init` (:meth:`~object.__init__`).
+
+ This cannot be used for objects with :c:macro:`Py_TPFLAGS_HAVE_GC` set in
+ :c:member:`~PyTypeObject.tp_flags`; use :c:macro:`PyObject_GC_New` instead.
+
+ Memory allocated by this macro must be freed with :c:func:`PyObject_Free`
+ (usually called via the object's :c:member:`~PyTypeObject.tp_free` slot).
+
+ .. note::
+
+ The returned memory is not guaranteed to have been completely zeroed
+ before it was initialized.
+
+ .. note::
+
+ This macro does not construct a fully initialized object of the given
+ type; it merely allocates memory and prepares it for further
+ initialization by :c:member:`~PyTypeObject.tp_init`. To construct a
+ fully initialized object, call *typeobj* instead. For example::
+
+ PyObject *foo = PyObject_CallNoArgs((PyObject *)&PyFoo_Type);
 
- Note that this function is unsuitable if *typeobj* has
- :c:macro:`Py_TPFLAGS_HAVE_GC` set. For such objects,
- use :c:func:`PyObject_GC_New` instead.
+ .. seealso::
+
+ * :c:func:`PyObject_Free`
+ * :c:macro:`PyObject_GC_New`
+ * :c:func:`PyType_GenericAlloc`
+ * :c:member:`~PyTypeObject.tp_alloc`
 
 
 .. c:macro:: PyObject_NewVar(TYPE, typeobj, size)
 
- Allocate a new Python object using the C structure type *TYPE* and the
- Python type object *typeobj* (``PyTypeObject*``).
- Fields not defined by the Python object header
- are not initialized. The allocated memory allows for the *TYPE* structure
- plus *size* (``Py_ssize_t``) fields of the size
- given by the :c:member:`~PyTypeObject.tp_itemsize` field of
- *typeobj*. This is useful for implementing objects like tuples, which are
- able to determine their size at construction time. Embedding the array of
- fields into the same allocation decreases the number of allocations,
- improving the memory management efficiency.
-
- Note that this function is unsuitable if *typeobj* has
- :c:macro:`Py_TPFLAGS_HAVE_GC` set. For such objects,
- use :c:func:`PyObject_GC_NewVar` instead.
+ Like :c:macro:`PyObject_New` except:
+
+ * It allocates enough memory for the *TYPE* structure plus *size*
+ (``Py_ssize_t``) fields of the size given by the
+ :c:member:`~PyTypeObject.tp_itemsize` field of *typeobj*.
+ * The memory is initialized like :c:func:`PyObject_InitVar`.
+
+ This is useful for implementing objects like tuples, which are able to
+ determine their size at construction time. Embedding the array of fields
+ into the same allocation decreases the number of allocations, improving the
+ memory management efficiency.
+
+ Avoid calling this directly to allocate memory for an object; call the type's
+ :c:member:`~PyTypeObject.tp_alloc` slot instead.
+
+ When populating a type's :c:member:`~PyTypeObject.tp_alloc` slot,
+ :c:func:`PyType_GenericAlloc` is preferred over a custom function that
+ simply calls this macro.
+
+ This cannot be used for objects with :c:macro:`Py_TPFLAGS_HAVE_GC` set in
+ :c:member:`~PyTypeObject.tp_flags`; use :c:macro:`PyObject_GC_NewVar`
+ instead.
+
+ Memory allocated by this function must be freed with :c:func:`PyObject_Free`
+ (usually called via the object's :c:member:`~PyTypeObject.tp_free` slot).
+
+ .. note::
+
+ The returned memory is not guaranteed to have been completely zeroed
+ before it was initialized.
+
+ .. note::
+
+ This macro does not construct a fully initialized object of the given
+ type; it merely allocates memory and prepares it for further
+ initialization by :c:member:`~PyTypeObject.tp_init`. To construct a
+ fully initialized object, call *typeobj* instead. For example::
+
+ PyObject *list_instance = PyObject_CallNoArgs((PyObject *)&PyList_Type);
+
+ .. seealso::
+
+ * :c:func:`PyObject_Free`
+ * :c:macro:`PyObject_GC_NewVar`
+ * :c:func:`PyType_GenericAlloc`
+ * :c:member:`~PyTypeObject.tp_alloc`
 
 
 .. c:function:: void PyObject_Del(void *op)

Doc/c-api/gcsupport.rst

@@ -57,11 +57,49 @@ rules:
  Analogous to :c:macro:`PyObject_New` but for container objects with the
  :c:macro:`Py_TPFLAGS_HAVE_GC` flag set.
 
+ Do not call this directly to allocate memory for an object; call the type's
+ :c:member:`~PyTypeObject.tp_alloc` slot instead.
+
+ When populating a type's :c:member:`~PyTypeObject.tp_alloc` slot,
+ :c:func:`PyType_GenericAlloc` is preferred over a custom function that
+ simply calls this macro.
+
+ Memory allocated by this macro must be freed with
+ :c:func:`PyObject_GC_Del` (usually called via the object's
+ :c:member:`~PyTypeObject.tp_free` slot).
+
+ .. seealso::
+
+ * :c:func:`PyObject_GC_Del`
+ * :c:macro:`PyObject_New`
+ * :c:func:`PyType_GenericAlloc`
+ * :c:member:`~PyTypeObject.tp_alloc`
+
+
 .. c:macro:: PyObject_GC_NewVar(TYPE, typeobj, size)
 
  Analogous to :c:macro:`PyObject_NewVar` but for container objects with the
  :c:macro:`Py_TPFLAGS_HAVE_GC` flag set.
 
+ Do not call this directly to allocate memory for an object; call the type's
+ :c:member:`~PyTypeObject.tp_alloc` slot instead.
+
+ When populating a type's :c:member:`~PyTypeObject.tp_alloc` slot,
+ :c:func:`PyType_GenericAlloc` is preferred over a custom function that
+ simply calls this macro.
+
+ Memory allocated by this macro must be freed with
+ :c:func:`PyObject_GC_Del` (usually called via the object's
+ :c:member:`~PyTypeObject.tp_free` slot).
+
+ .. seealso::
+
+ * :c:func:`PyObject_GC_Del`
+ * :c:macro:`PyObject_NewVar`
+ * :c:func:`PyType_GenericAlloc`
+ * :c:member:`~PyTypeObject.tp_alloc`
+
+
 .. c:function:: PyObject* PyUnstable_Object_GC_NewWithExtraData(PyTypeObject *type, size_t extra_size)
 
  Analogous to :c:macro:`PyObject_GC_New` but allocates *extra_size*
@@ -73,6 +111,10 @@ rules:
  The extra data will be deallocated with the object, but otherwise it is
  not managed by Python.
 
+ Memory allocated by this function must be freed with
+ :c:func:`PyObject_GC_Del` (usually called via the object's
+ :c:member:`~PyTypeObject.tp_free` slot).
+
  .. warning::
  The function is marked as unstable because the final mechanism
  for reserving extra data after an instance is not yet decided.
@@ -136,6 +178,21 @@ rules:
  Releases memory allocated to an object using :c:macro:`PyObject_GC_New` or
  :c:macro:`PyObject_GC_NewVar`.
 
+ Do not call this directly to free an object's memory; call the type's
+ :c:member:`~PyTypeObject.tp_free` slot instead.
+
+ Do not use this for memory allocated by :c:macro:`PyObject_New`,
+ :c:macro:`PyObject_NewVar`, or related allocation functions; use
+ :c:func:`PyObject_Free` instead.
+
+ .. seealso::
+
+ * :c:func:`PyObject_Free` is the non-GC equivalent of this function.
+ * :c:macro:`PyObject_GC_New`
+ * :c:macro:`PyObject_GC_NewVar`
+ * :c:func:`PyType_GenericAlloc`
+ * :c:member:`~PyTypeObject.tp_free`
+
 
 .. c:function:: void PyObject_GC_UnTrack(void *op)