10000 GH-95245: Document use of `MANAGED` flags instead of offsets. by markshannon · Pull Request #96044 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

GH-95245: Document use of MANAGED flags instead of offsets. #96044

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Aug 30, 2022
Merged

GH-95245: Document use of MANAGED flags instead of offsets. #96044

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6b6d032
Update section on adding weakrefs.
markshannon Aug 17, 2022
9211dbd
Update c-api docs regarding tp_dictoffset and tp_weaklistoffset.
markshannon Aug 17, 2022
bd5cad4
Fix typo
markshannon Aug 17, 2022
5ad1362
Fix formatting.
markshannon Aug 17, 2022
a508c00
Implement mdboom's suggestions.
markshannon Aug 30, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
Update section on adding weakrefs.
  • Loading branch information
@markshannon
markshannon committed Aug 17, 2022
commit 6b6d032d47599db23facf5bce5caa92a49cdb539
30 changes: 8 additions & 22 deletions Doc/extending/newtypes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -570,33 +570,20 @@ performance-critical objects (such as numbers).
.. seealso::
Documentation for the :mod:`weakref` module.

For an object to be weakly referencable, the extension type must do two things:
For an object to be weakly referencable, the extension type must set the
``Py_TPFLAGS_MANAGED_WEAKREF`` bit of the :c:member:`~PyTypeObject.`tp_flags`
field. The legacy :c:member:`~PyTypeObject.tp_weaklistoffset` field should
be left as zero.

#. Include a :c:type:`PyObject\*` field in the C object structure dedicated to
the weak reference mechanism. The object's constructor should leave it
``NULL`` (which is automatic when using the default
:c:member:`~PyTypeObject.tp_alloc`).

#. Set the :c:member:`~PyTypeObject.tp_weaklistoffset` type member
to the offset of the aforementioned field in the C object structure,
so that the interpreter knows how to access and modify that field.

Concretely, here is how a trivial object structure would be augmented
with the required field::

typedef struct {
PyObject_HEAD
PyObject *weakreflist; /* List of weak references */
} TrivialObject;

And the corresponding member in the statically declared type object::
Concretely, here is how the statically declared type object would look::

static PyTypeObject TrivialType = {
PyVarObject_HEAD_INIT(NULL, 0)
/* ... other members omitted for brevity ... */
.tp_weaklistoffset = offsetof(TrivialObject, weakreflist),
.tp_flags = Py_TPFLAGS_MANAGED_WEAKREF | ...,
};


The only further addition is that ``tp_dealloc`` needs to clear any weak
references (by calling :c:func:`PyObject_ClearWeakRefs`) if the field is
non-``NULL``::
Expand All @@ -605,8 +592,7 @@ non-``NULL``::
Trivial_dealloc(TrivialObject *self)
{
/* Clear weakrefs first before calling any destructors */
if (self->weakreflist != NULL)
PyObject_ClearWeakRefs((PyObject *) self);
PyObject_ClearWeakRefs((PyObject *) self);
/* ... remainder of destruction code omitted for brevity ... */
Py_TYPE(self)->tp_free((PyObject *) self);
}
Expand Down
0