From d512fe441b4be668593afba9e4bfb61b361ee152 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Wed, 17 Mar 2021 15:12:13 +1100 Subject: Comments: document memory management for `BPyPropStore` --- source/blender/python/intern/bpy_props.c | 37 ++++++++++++++++++++++++++++---- 1 file changed, 33 insertions(+), 4 deletions(-) (limited to 'source/blender/python') diff --git a/source/blender/python/intern/bpy_props.c b/source/blender/python/intern/bpy_props.c index b6149175c91..e4e6b3ea8f2 100644 --- a/source/blender/python/intern/bpy_props.c +++ b/source/blender/python/intern/bpy_props.c @@ -198,15 +198,44 @@ static const EnumPropertyItem property_subtype_array_items[] = { * \{ */ /** - * Slots for #PyObject slots stored in #PropertyRNA.py_data (these hold a reference). - * #bpy_prop_callback_free_py_data manages decrementing. + * Store #PyObject data for a dynamically defined property. + * Currently this is only used to store call-back functions. + * Properties that don't use custom-callbacks wont allocate this struct. + * + * Memory/Reference Management + * --------------------------- + * + * This struct adds/removes the user-count of each #PyObject it references, + * it's needed in case the function is removed from the class (unlikely but possible), + * also when an annotation evaluates to a `lambda` with Python 3.10 and newer e.g: T86332. + * + * Pointers to this struct are held in: + * + * - #PropertyRNA.py_data (owns the memory). + * Freed when the RNA property is freed. + * + * - #g_bpy_prop_store_list (borrows the memory) + * Having a global list means the users can be visited by the GC and cleared on exit. + * + * This list can't be used for freeing as #BPyPropStore doesn't hold a #PropertyRNA back-pointer, + * (while it could be supported it would only complicate things). + * + * All RNA properties are freed after Python has been shut-down. + * At that point Python user counts can't be touched and must have already been dealt with. + * + * Decrementing users is handled by: + * + * - #bpy_prop_py_data_remove manages decrementing at run-time (when a property is removed), + * + * - #BPY_rna_props_clear_all does this on exit for all dynamic properties. */ struct BPyPropStore { struct BPyPropStore *next, *prev; /** - * Only store #PyObject types, can be cast to an an array and operated on. - * NULL members are ignored/skipped. */ + * Only store #PyObject types, so this member can be cast to an array and iterated over. + * NULL members are skipped. + */ struct { /** Wrap: `RNA_def_property_*_funcs` (depending on type). */ PyObject *get_fn; -- cgit v1.2.3