doc: SCHWED-4345 add note on memory management

modules/doc/intro-01.rst

@@ -230,4 +230,32 @@ select the backbone atoms and then save it:
 That's it for the mol module. Continue with :doc:`part two<intro-02>` of the 
 tutorial.
 
+.. _memory_management:
+
+Memory management
+--------------------------------------------------------------------------------
+
+Because the data is managed by OST's underlying C++ layer, some behaviors can
+be somewhat surprising to Python developers. One such behavior is that
+:class:`entities <ost.mol.EntityHandle>` store all the data about chains,
+residues and atoms.
+
+Once an entity is deleted, all :class:`chains <ost.mol.ChainHandle>`,
+:class:`residues <ost.mol.ResidueHandle>` and
+:class:`atoms <ost.mol.AtomHandle>` that refer to it become invalid, so the
+following code is invalid and raises an exception:
+
+.. code-block:: python
+
+   ent = io.LoadPDB('1crn', remote=True)
+   my_residue = ent.FindResidue("A", 1)
+   print(my_residue.qualified_name)
+   # A.THR1
+   ent = None
+   print(my_residue.qualified_name)
+   # Exception: Can not access invalid handle or view
+
+This can frequently be an issue when you return data from a function.
+Make sure the entity is always defined outside of the function.
+
 ..  LocalWords:  attr

modules/mol/base/doc/entity.rst

@@ -356,7 +356,7 @@ Chain Handle
 .. class:: ChainHandle
 
   A chain of one or more :class:`residues <ResidueHandle>`. Chains are always 
-  part of an entity.
+  part of an entity (see :ref:`note on memory management <memory_management>`).
 
   .. attribute:: properties
 
@@ -604,7 +604,8 @@ Residue Handle
   in a polymer, e.g. in a protein, DNA or RNA. A residue consists of one or 
   more :class:`atoms <AtomHandle>`. Residues are always part of a 
   :class:`ChainHandle`, even if they are ligands or water molecules where the 
-  concept of a chain does not apply.
+  concept of a chain does not apply, and of an entity (see
+  :ref:`note on memory management <memory_management>`).
 
   .. attribute:: properties
 
@@ -1041,7 +1042,8 @@ Atom Handle
 .. class:: AtomHandle
 
   Represents an atom in a molecular structure. Atoms are always part of a 
-  residue.
+  residue and of an entity (see
+  :ref:`note on memory management <memory_management>`)
 
   .. attribute:: properties