[Bf-blender-cvs] [0d042c8cca1] master: RNA: document Python instancing for ID's and RNA types

[Campbell Barton]

Commit: 0d042c8cca13823c976440db37cb9e1e072d5dd5
Author: Campbell Barton
Date:   Thu Jan 7 21:32:43 2021 +1100
Branches: master
https://developer.blender.org/rB0d042c8cca13823c976440db37cb9e1e072d5dd5

RNA: document Python instancing for ID's and RNA types

Document some of the less obvious implications for
re-using Python instances.

===================================================================

M	source/blender/makesdna/DNA_ID.h
M	source/blender/makesrna/intern/rna_internal_types.h

===================================================================

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 */