From 1f1713a47386ff84148315f8340f19fd7fc81f87 Mon Sep 17 00:00:00 2001
From: Xavier Robin <xavalias-github@xavier.robin.name>
Date: Thu, 27 Jul 2023 11:02:06 +0200
Subject: [PATCH] doc: SCHWED-4345 add note on memory management
---
modules/doc/intro-01.rst | 28 ++++++++++++++++++++++++++++
modules/mol/base/doc/entity.rst | 8 +++++---
2 files changed, 33 insertions(+), 3 deletions(-)
diff --git a/modules/doc/intro-01.rst b/modules/doc/intro-01.rst
index 98c3427e7..aec5d8d3b 100644
--- a/modules/doc/intro-01.rst
+++ b/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
diff --git a/modules/mol/base/doc/entity.rst b/modules/mol/base/doc/entity.rst
index 14e3d9fa4..4238bfbce 100644
--- a/modules/mol/base/doc/entity.rst
+++ b/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
--
GitLab