Skip to content

PyObject_CallFinalizerFromDealloc is undocumented #75459

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

Jump to bottom
Closed
pv mannequin opened this issue Aug 25, 2017 · 2 comments
Closed

PyObject_CallFinalizerFromDealloc is undocumented #75459

pv mannequin opened this issue Aug 25, 2017 · 2 comments
Labels
docs Documentation in the Doc dir topic-C-API

Comments

@pv
Copy link
Mannequin

pv mannequin commented Aug 25, 2017 •
edited by bedevere-app bot
Loading

BPO 31276
Nosy @pv

Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2017-08-25.14:26:48.286>
labels = ['3.7', 'docs']
title = 'PyObject_CallFinalizerFromDealloc is undocumented'
updated_at = <Date 2017-08-25.14:26:48.286>
user = 'https://github.com/pv'

bugs.python.org fields:

activity = <Date 2017-08-25.14:26:48.286>
actor = 'pv'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2017-08-25.14:26:48.286>
creator = 'pv'
dependencies = []
files = []
hgrepos = []
issue_num = 31276
keywords = []
message_count = 1.0
messages = ['300842']
nosy_count = 2.0
nosy_names = ['pv', 'docs@python']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue31276'
versions = ['Python 3.7']

Linked PRs
@pv
Copy link
Mannequin Author

pv mannequin commented Aug 25, 2017

It's unclear if PyObject_CallFinalizerFromDealloc is a public function
or not. It is not documented, but it seems there's no other way to
ensure that tp_finalize runs, at least for objects without
Py_TPFLAGS_HAVE_GC.

In the documentation of tp_finalize (https://docs.python.org/3/c-api/typeobj.html?highlight=tp_finalize#c.PyTypeObject.tp_finalize)
there is the sentence:

"""It is called either from the garbage collector (if the instance is
part of an isolated reference cycle) or just before the object is
deallocated."""

However, it appears it is necessary to call it explicitly from any
user-provided tp_dealloc. Indeed, there are several calls to
PyObject_CallFinalizerFromDealloc in cpython/Modules/* e.g. in
posixmodule.c:ScandirIterator_dealloc

@pv pv mannequin added the 3.7 (EOL) end of life label Aug 25, 2017
@pv pv mannequin assigned docspython Aug 25, 2017
@pv pv mannequin added the docs Documentation in the Doc dir label Aug 25, 2017
@ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
@rhansen rhansen mentioned this issue Oct 22, 2024
Open
rhansen added a commit to rhansen/cpython that referenced this issue Oct 25, 2024
@rhansen
pythongh-75459: Doc: C API: Improve object life cycle documentation
5187f31 
  * Add "cyclic isolate" to the glossary.
  * Add a new "Object Life Cycle" page.
    * Illustrate the order of life cycle functions.
    * Document `PyObject_CallFinalizer` and
      `PyObject_CallFinalizerFromDealloc`.
  * `PyObject_Init` does not call `tp_init`.
  * `PyObject_New`:
    * also initializes the memory
    * does not call `tp_alloc`, `tp_new`, or `tp_init`
    * should not be used for GC-enabled objects
    * memory must be freed by `PyObject_Free`
  * `PyObject_GC_New` memory must be freed by `PyObject_GC_Del`.
  * Warn that garbage collector functions can be called from any
    thread.
  * `tp_finalize` and `tp_clear`:
    * Only called when there's a cyclic isolate.
    * Only one object in the cyclic isolate is finalized/cleared at a
      time.
    * Clearly warn that they might not be called.
    * They can optionally be manually called from `tp_dealloc` (via
      `PyObject_CallFinalizerFromDealloc` in the case of
      `tp_finalize`).
  * `tp_finalize`:
    * Reference `object.__del__`.
    * The finalizer can resurrect the object.
    * Suggest `PyErr_GetRaisedException` and
      `PyErr_SetRaisedException` instead of the deprecated
      `PyErr_Fetch` and `PyErr_Restore` functions.
    * Add links to `PyErr_GetRaisedException` and
      `PyErr_SetRaisedException`.
    * Suggest using `PyErr_WriteUnraisable` if an exception is raised
      during finalization.
    * Rename the example function from `local_finalize` to
      `foo_finalize` for consistency with the `tp_dealloc`
      documentation and as a hint that the name isn't special.
    * Minor wording and sylistic tweaks.
    * Warn that `tp_finalize` can be called during shutdown.
@bedevere-app bedevere-app bot mentioned this issue Oct 25, 2024
Merged
rhansen added a commit to rhansen/cpython that referenced this issue Oct 25, 2024
@rhansen
pythongh-75459: Doc: C API: Improve object life cycle documentation
7a65fb3 
  * Add "cyclic isolate" to the glossary.
  * Add a new "Object Life Cycle" page.
    * Illustrate the order of life cycle functions.
    * Document `PyObject_CallFinalizer` and
      `PyObject_CallFinalizerFromDealloc`.
  * `PyObject_Init` does not call `tp_init`.
  * `PyObject_New`:
    * also initializes the memory
    * does not call `tp_alloc`, `tp_new`, or `tp_init`
    * should not be used for GC-enabled objects
    * memory must be freed by `PyObject_Free`
  * `PyObject_GC_New` memory must be freed by `PyObject_GC_Del`.
  * Warn that garbage collector functions can be called from any
    thread.
  * `tp_finalize` and `tp_clear`:
    * Only called when there's a cyclic isolate.
    * Only one object in the cyclic isolate is finalized/cleared at a
      time.
    * Clearly warn that they might not be called.
    * They can optionally be manually called from `tp_dealloc` (via
      `PyObject_CallFinalizerFromDealloc` in the case of
      `tp_finalize`).
  * `tp_finalize`:
    * Reference `object.__del__`.
    * The finalizer can resurrect the object.
    * Suggest `PyErr_GetRaisedException` and
      `PyErr_SetRaisedException` instead of the deprecated
      `PyErr_Fetch` and `PyErr_Restore` functions.
    * Add links to `PyErr_GetRaisedException` and
      `PyErr_SetRaisedException`.
    * Suggest using `PyErr_WriteUnraisable` if an exception is raised
      during finalization.
    * Rename the example function from `local_finalize` to
      `foo_finalize` for consistency with the `tp_dealloc`
      documentation and as a hint that the name isn't special.
    * Minor wording and sylistic tweaks.
    * Warn that `tp_finalize` can be called during shutdown.
rhansen added a commit to rhansen/cpython that referenced this issue Oct 25, 2024
@rhansen
pythongh-75459: Doc: C API: Improve object life cycle documentation
2093734 
  * Add "cyclic isolate" to the glossary.
  * Add a new "Object Life Cycle" page.
    * Illustrate the order of life cycle functions.
    * Document `PyObject_CallFinalizer` and
      `PyObject_CallFinalizerFromDealloc`.
  * `PyObject_Init` does not call `tp_init`.
  * `PyObject_New`:
    * also initializes the memory
    * does not call `tp_alloc`, `tp_new`, or `tp_init`
    * should not be used for GC-enabled objects
    * memory must be freed by `PyObject_Free`
  * `PyObject_GC_New` memory must be freed by `PyObject_GC_Del`.
  * Warn that garbage collector functions can be called from any
    thread.
  * `tp_finalize` and `tp_clear`:
    * Only called when there's a cyclic isolate.
    * Only one object in the cyclic isolate is finalized/cleared at a
      time.
    * Clearly warn that they might not be called.
    * They can optionally be manually called from `tp_dealloc` (via
      `PyObject_CallFinalizerFromDealloc` in the case of
      `tp_finalize`).
  * `tp_finalize`:
    * Reference `object.__del__`.
    * The finalizer can resurrect the object.
    * Suggest `PyErr_GetRaisedException` and
      `PyErr_SetRaisedException` instead of the deprecated
      `PyErr_Fetch` and `PyErr_Restore` functions.
    * Add links to `PyErr_GetRaisedException` and
      `PyErr_SetRaisedException`.
    * Suggest using `PyErr_WriteUnraisable` if an exception is raised
      during finalization.
    * Rename the example function from `local_finalize` to
      `foo_finalize` for consistency with the `tp_dealloc`
      documentation and as a hint that the name isn't special.
    * Minor wording and sylistic tweaks.
    * Warn that `tp_finalize` can be called during shutdown.
rhansen added a commit to rhansen/cpython that referenced this issue Oct 25, 2024
@rhansen
pythongh-75459: Doc: C API: Improve object life cycle documentation
44e12fd 
  * Add "cyclic isolate" to the glossary.
  * Add a new "Object Life Cycle" page.
    * Illustrate the order of life cycle functions.
    * Document `PyObject_CallFinalizer` and
      `PyObject_CallFinalizerFromDealloc`.
  * `PyObject_Init` does not call `tp_init`.
  * `PyObject_New`:
    * also initializes the memory
    * does not call `tp_alloc`, `tp_new`, or `tp_init`
    * should not be used for GC-enabled objects
    * memory must be freed by `PyObject_Free`
  * `PyObject_GC_New` memory must be freed by `PyObject_GC_Del`.
  * Warn that garbage collector functions can be called from any
    thread.
  * `tp_finalize` and `tp_clear`:
    * Only called when there's a cyclic isolate.
    * Only one object in the cyclic isolate is finalized/cleared at a
      time.
    * Clearly warn that they might not be called.
    * They can optionally be manually called from `tp_dealloc` (via
      `PyObject_CallFinalizerFromDealloc` in the case of
      `tp_finalize`).
  * `tp_finalize`:
    * Reference `object.__del__`.
    * The finalizer can resurrect the object.
    * Suggest `PyErr_GetRaisedException` and
      `PyErr_SetRaisedException` instead of the deprecated
      `PyErr_Fetch` and `PyErr_Restore` functions.
    * Add links to `PyErr_GetRaisedException` and
      `PyErr_SetRaisedException`.
    * Suggest using `PyErr_WriteUnraisable` if an exception is raised
      during finalization.
    * Rename the example function from `local_finalize` to
      `foo_finalize` for consistency with the `tp_dealloc`
      documentation and as a hint that the name isn't special.
    * Minor wording and sylistic tweaks.
    * Warn that `tp_finalize` can be called during shutdown.
rhansen added a commit to rhansen/cpython that referenced this issue Oct 25, 2024
@rhansen
pythongh-75459: Doc: C API: Improve object life cycle documentation
be22691 
  * Add "cyclic isolate" to the glossary.
  * Add a new "Object Life Cycle" page.
    * Illustrate the order of life cycle functions.
    * Document `PyObject_CallFinalizer` and
      `PyObject_CallFinalizerFromDealloc`.
  * `PyObject_Init` does not call `tp_init`.
  * `PyObject_New`:
    * also initializes the memory
    * does not call `tp_alloc`, `tp_new`, or `tp_init`
    * should not be used for GC-enabled objects
    * memory must be freed by `PyObject_Free`
  * `PyObject_GC_New` memory must be freed by `PyObject_GC_Del`.
  * Warn that garbage collector functions can be called from any
    thread.
  * `tp_finalize` and `tp_clear`:
    * Only called when there's a cyclic isolate.
    * Only one object in the cyclic isolate is finalized/cleared at a
      time.
    * Clearly warn that they might not be called.
    * They can optionally be manually called from `tp_dealloc` (via
      `PyObject_CallFinalizerFromDealloc` in the case of
      `tp_finalize`).
  * `tp_finalize`:
    * Reference `object.__del__`.
    * The finalizer can resurrect the object.
    * Suggest `PyErr_GetRaisedException` and
      `PyErr_SetRaisedException` instead of the deprecated
      `PyErr_Fetch` and `PyErr_Restore` functions.
    * Add links to `PyErr_GetRaisedException` and
      `PyErr_SetRaisedException`.
    * Suggest using `PyErr_WriteUnraisable` if an exception is raised
      during finalization.
    * Rename the example function from `local_finalize` to
      `foo_finalize` for consistency with the `tp_dealloc`
      documentation and as a hint that the name isn't special.
    * Minor wording and sylistic tweaks.
    * Warn that `tp_finalize` can be called during shutdown.
rhansen added a commit to rhansen/cpython that referenced this issue Oct 25, 2024
@rhansen
pythongh-75459: Doc: C API: Improve object life cycle documentation
d804c6c 
  * Add "cyclic isolate" to the glossary.
  * Add a new "Object Life Cycle" page.
    * Illustrate the order of life cycle functions.
    * Document `PyObject_CallFinalizer` and
      `PyObject_CallFinalizerFromDealloc`.
  * `PyObject_Init` does not call `tp_init`.
  * `PyObject_New`:
    * also initializes the memory
    * does not call `tp_alloc`, `tp_new`, or `tp_init`
    * should not be used for GC-enabled objects
    * memory must be freed by `PyObject_Free`
  * `PyObject_GC_New` memory must be freed by `PyObject_GC_Del`.
  * Warn that garbage collector functions can be called from any
    thread.
  * `tp_finalize` and `tp_clear`:
    * Only called when there's a cyclic isolate.
    * Only one object in the cyclic isolate is finalized/cleared at a
      time.
    * Clearly warn that they might not be called.
    * They can optionally be manually called from `tp_dealloc` (via
      `PyObject_CallFinalizerFromDealloc` in the case of
      `tp_finalize`).
  * `tp_finalize`:
    * Reference `object.__del__`.
    * The finalizer can resurrect the object.
    * Suggest `PyErr_GetRaisedException` and
      `PyErr_SetRaisedException` instead of the deprecated
      `PyErr_Fetch` and `PyErr_Restore` functions.
    * Add links to `PyErr_GetRaisedException` and
      `PyErr_SetRaisedException`.
    * Suggest using `PyErr_WriteUnraisable` if an exception is raised
      during finalization.
    * Rename the example function from `local_finalize` to
      `foo_finalize` for consistency with the `tp_dealloc`
      documentation and as a hint that the name isn't special.
    * Minor wording and sylistic tweaks.
    * Warn that `tp_finalize` can be called during shutdown.
rhansen added a commit to rhansen/cpython that referenced this issue Oct 25, 2024
@rhansen
pythongh-75459: Doc: C API: Improve object life cycle documentation
bc32398 
  * Add "cyclic isolate" to the glossary.
  * Add a new "Object Life Cycle" page.
    * Illustrate the order of life cycle functions.
    * Document `PyObject_CallFinalizer` and
      `PyObject_CallFinalizerFromDealloc`.
  * `PyObject_Init` does not call `tp_init`.
  * `PyObject_New`:
    * also initializes the memory
    * does not call `tp_alloc`, `tp_new`, or `tp_init`
    * should not be used for GC-enabled objects
    * memory must be freed by `PyObject_Free`
  * `PyObject_GC_New` memory must be freed by `PyObject_GC_Del`.
  * Warn that garbage collector functions can be called from any
    thread.
  * `tp_finalize` and `tp_clear`:
    * Only called when there's a cyclic isolate.
    * Only one object in the cyclic isolate is finalized/cleared at a
      time.
    * Clearly warn that they might not be called.
    * They can optionally be manually called from `tp_dealloc` (via
      `PyObject_CallFinalizerFromDealloc` in the case of
      `tp_finalize`).
  * `tp_finalize`:
    * Reference `object.__del__`.
    * The finalizer can resurrect the object.
    * Suggest `PyErr_GetRaisedException` and
      `PyErr_SetRaisedException` instead of the deprecated
      `PyErr_Fetch` and `PyErr_Restore` functions.
    * Add links to `PyErr_GetRaisedException` and
      `PyErr_SetRaisedException`.
    * Suggest using `PyErr_WriteUnraisable` if an exception is raised
      during finalization.
    * Rename the example function from `local_finalize` to
      `foo_finalize` for consistency with the `tp_dealloc`
      documentation and as a hint that the name isn't special.
    * Minor wording and sylistic tweaks.
    * Warn that `tp_finalize` can be called during shutdown.
rhansen added a commit to rhansen/cpython that referenced this issue Oct 25, 2024
@rhansen
pythongh-75459: Doc: Tell sphinx to run graphviz
361eaca
rhansen added a commit to rhansen/cpython that referenced this issue Oct 25, 2024
@rhansen
Revert "pythongh-75459: Doc: Tell sphinx to run graphviz"
b42b58d 
This reverts commit 361eaca.
encukou added a commit that referenced this issue May 20, 2025
@rhansen @encukou @ZeroIntensity
gh-75459: Doc: C API: Improve object life cycle documentation (GH-125962
3246ea5 
)

  * Add "cyclic isolate" to the glossary.
  * Add a new "Object Life Cycle" page.
  * Improve docs for related API, with special focus on cross-references and warnings

Co-authored-by: Petr Viktorin <[email protected]>
Co-authored-by: Peter Bierma <[email protected]>
@encukou
Copy link
Member

encukou commented May 20, 2025

Thank you @rhansen for taking the time to understand and document the situation, and @ZeroIntensity for finishing up!

@picnixz picnixz removed the 3.7 (EOL) end of life label May 20, 2025
miss-islington pushed a commit to miss-islington/cpython that referenced this issue May 20, 2025
@rhansen @encukou
@ZeroIntensity @miss-islington
pythongh-75459: Doc: C API: Improve object life cycle documentation (p…
b412e02 
…ythonGH-125962)

  * Add "cyclic isolate" to the glossary.
  * Add a new "Object Life Cycle" page.
  * Improve docs for related API, with special focus on cross-references and warnings
(cherry picked from commit 3246ea5)

Co-authored-by: Richard Hansen <[email protected]>
Co-authored-by: Petr Viktorin <[email protected]>
Co-authored-by: Peter Bierma <[email protected]>
@bedevere-app bedevere-app bot mentioned this issue May 20, 2025
Merged
encukou added a commit that referenced this issue May 20, 2025
@miss-islington @rhansen
@encukou @ZeroIntensity
[3.14] gh-75459: Doc: C API: Improve object life cycle documentation (G…
6074e1e 
…H-125962) (GH-134344)

gh-75459: Doc: C API: Improve object life cycle documentation (GH-125962)

  * Add "cyclic isolate" to the glossary.
  * Add a new "Object Life Cycle" page.
  * Improve docs for related API, with special focus on cross-references and warnings
(cherry picked from commit 3246ea5)

Co-authored-by: Richard Hansen <[email protected]>
Co-authored-by: Petr Viktorin <[email protected]>
Co-authored-by: Peter Bierma <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
docs Documentation in the Doc dir topic-C-API
Projects
docs issues
Status: Todo
Milestone
No milestone
Development

No branches or pull requests
3 participants
@encukou @picnixz @ZeroIntensity