diff options
author | Campbell Barton <ideasman42@gmail.com> | 2021-01-07 13:32:43 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2021-01-07 13:36:39 +0300 |
commit | 0d042c8cca13823c976440db37cb9e1e072d5dd5 (patch) | |
tree | 7d66470087a5c1b6f65f9f09b73b5bae3c4f800e | |
parent | 4a771263fdd3c2e8cb408de4dd187430b33eff81 (diff) |
RNA: document Python instancing for ID's and RNA types
Document some of the less obvious implications for
re-using Python instances.
-rw-r--r-- | source/blender/makesdna/DNA_ID.h | 14 | ||||
-rw-r--r-- | source/blender/makesrna/intern/rna_internal_types.h | 11 |
2 files changed, 25 insertions, 0 deletions
diff --git a/source/blender/makesdna/DNA_ID.h b/source/blender/makesdna/DNA_ID.h index 265baa16cc5..51c47e917f1 100644 --- a/source/blender/makesdna/DNA_ID.h +++ b/source/blender/makesdna/DNA_ID.h @@ -314,6 +314,20 @@ typedef struct ID { */ struct ID *orig_id; + /** + * Holds the #PyObject reference to the ID (initialized on demand). + * + * This isn't essential, it could be removed however it gives some advantages: + * + * - Every time the #ID is accessed a #BPy_StructRNA doesn't have to be created & destroyed + * (consider all the polling and drawing functions that access ID's). + * + * - When this #ID is deleted, the #BPy_StructRNA can be invalidated + * so accessing it from Python raises an exception instead of crashing. + * + * This is of limited benefit though, as it doesn't apply to non #ID data + * that references this ID (the bones of an armature or the modifiers of an object for e.g.). + */ void *py_instance; void *_pad1; } ID; diff --git a/source/blender/makesrna/intern/rna_internal_types.h b/source/blender/makesrna/intern/rna_internal_types.h index 01c406104d7..e6ed0f69300 100644 --- a/source/blender/makesrna/intern/rna_internal_types.h +++ b/source/blender/makesrna/intern/rna_internal_types.h @@ -545,6 +545,17 @@ struct StructRNA { /* function to register/unregister subclasses */ StructRegisterFunc reg; StructUnregisterFunc unreg; + /** + * Optionally support reusing Python instances for this type. + * + * Without this, an operator class created for #wmOperatorType.invoke (for example) + * would have a different instance passed to the #wmOperatorType.modal callback. + * So any variables assigned to `self` from Python would not be available to other callbacks. + * + * Being able to access the instance also has the advantage that we can invalidate + * the Python instance when the data has been removed, see: #BPY_DECREF_RNA_INVALIDATE + * so accessing the variables from Python raises an exception instead of crashing. + */ StructInstanceFunc instance; /* callback to get id properties */ |