Documentation/Nightly/Developers/Tutorials/MemoryManagement - Revision history

Lasso: Moved to readthedocs

2022-02-04T20:02:57Z

Moved to readthedocs

Lasso: /* Python scripts and scripted modules */

2017-06-22T15:06:57Z

Python scripts and scripted modules

Lasso: /* Python scripts and scripted modules */

2016-10-18T14:54:49Z

Python scripts and scripted modules

Lasso: /* Pointers to VTK object */

2015-11-04T16:54:27Z

Pointers to VTK object

Lasso: /* Pointers to VTK object */

2015-11-04T16:47:23Z

Pointers to VTK object

Lasso at 14:22, 21 March 2014

2014-03-21T14:22:35Z

Lasso at 14:22, 21 March 2014

2014-03-21T14:22:14Z

Lasso at 16:02, 31 October 2013

2013-10-31T16:02:32Z

Lasso: Made the memory management differences more clear between C++ and Python

2013-10-31T16:01:58Z

Made the memory management differences more clear between C++ and Python

UpdateBot: Prepend documentation/versioncheck template. See http://na-mic.org/Mantis/view.php?id=2887

2013-06-14T07:57:32Z

Prepend documentation/versioncheck template. See http://na-mic.org/Mantis/view.php?id=2887

@@ Line 1: / Line 1: @@
 <noinclude>{{documentation/versioncheck}}</noinclude>
-= Pointers to VTK object =
+{{documentation/banner
+| text  = [https://slicer.readthedocs.io/en/latest/developer_guide/advanced_topics.html#memory-management This page has been moved to read-the-docs.]
-If you are not familiar with VTK's memory management read this [http://aosabook.org/en/vtk.html general introduction] and this [http://www.vtk.org/Wiki/VTK/Tutorials/SmartPointers page describing usage of smart pointers]. See Slicer-specific use cases and recommendations below.
+| background-color = 8FBC8F }}

@@ Line 66: / Line 66: @@
 For example, instead of using the CreateNodeByClass factory method and call UnRegister manually:
-  n = slicer.mrmlScene.CreateNodeByClass('vtkMRMLViewNode')
+  n = slicer.mrmlScene.CreateNodeByClass('vtkMRMLLinearTransformNode')
   slicer.mrmlScene.AddNode(n)
   n.UnRegister(slicer.mrmlScene)
-this should be used (if the name of the node is known when the script is written):
+this should be used:
-  n = slicer.mrmlScene.AddNode(slicer.vtkMRMLViewNode())
+ n = slicer.mrmlScene.AddNewNodeByClass('vtkMRMLLinearTransformNode')
 Note: MRML scene's CreateNodeByClass creates a node with the default settings set in the scene for that node type (using [https://www.slicer.org/doc/html/classvtkMRMLScene.html#ae302c5ed4aabb2910bc35dcc9aa2513f vtkMRMLScene::AddDefaultNode]).

@@ Line 67: / Line 67: @@
 For example, instead of using the CreateNodeByClass factory method and call UnRegister manually:
   n = slicer.mrmlScene.CreateNodeByClass('vtkMRMLViewNode')
-  slicer.mrmlScene.addNode(n)
+  slicer.mrmlScene.AddNode(n)
   n.UnRegister(slicer.mrmlScene)
 this should be used (if the name of the node is known when the script is written):
-   n = slicer.mrmlScene.addNode(slicer.vtkMRMLViewNode())
+   n = slicer.mrmlScene.AddNode(slicer.vtkMRMLViewNode())
 or this should be used (if the name of the node is generated at runtime):
    n = eval('slicer.mrmlScene.AddNode(slicer.%s())' % 'vtkMRMLViewNode')

@@ Line 2: / Line 2: @@
 = Pointers to VTK object =
 Calling the plain New() method of VTK objects and storing the returned pointer in a plain pointer should be avoided, as this very often causes memory leaks.
@@ Line 27: / Line 29: @@
 * we don't know the exact object type that we want to create at the time of the pointer creation (e.g., we create a vtkSmartPointer<vtkMRMLVolumeNode> and later set it to point to a vtkMRMLScalarVolumeNode or vtkMRMLVectorVolumeNode), or
 * we need to take the ownership of an already created object (using vtkSmartPointer::Take(...), see a examples below)
 = Factory methods =

@@ Line 27: / Line 27: @@
 * we don't know the exact object type that we want to create at the time of the pointer creation (e.g., we create a vtkSmartPointer<vtkMRMLVolumeNode> and later set it to point to a vtkMRMLScalarVolumeNode or vtkMRMLVectorVolumeNode), or
 * we need to take the ownership of an already created object (using vtkSmartPointer::Take(...), see a examples below)
 = Factory methods =

@@ Line 24: / Line 24: @@
 vtkNew is preferred in general for new object creation, as it has a simpler syntax and used almost exclusively in the Slicer core source code. A slight inconvenience is that when we need use the GetPointer() method to get the actual pointer value.
-A vtkSmartPointer pointer can be created without actually creating an object, so vtkSmartPointer should be used when
+A vtkSmartPointer pointer can be created without actually creating an object, so vtkSmartPointer should be used when:
-* we don't know the exact object type that we want to create at the time of the pointer creation (e.g., we create a vtkSmartPointer<vtkMRMLVolumeNode> and later set it to point to a vtkMRMLScalarVolumeNode or vtkMRMLVectorVolumeNode)
+* we don't know the exact object type that we want to create at the time of the pointer creation (e.g., we create a vtkSmartPointer<vtkMRMLVolumeNode> and later set it to point to a vtkMRMLScalarVolumeNode or vtkMRMLVectorVolumeNode), or
 * we need to take the ownership of an already created object (using vtkSmartPointer::Take(...), see a examples below)

← Older revision		Revision as of 14:22, 21 March 2014
Line 1:		Line 1:
	<noinclude>{{documentation/versioncheck}}</noinclude>		<noinclude>{{documentation/versioncheck}}</noinclude>
		+
		+	= Pointers to VTK object =
		+
		+	Calling the plain New() method of VTK objects and storing the returned pointer in a plain pointer should be avoided, as this very often causes memory leaks.
		+
		+	Bad, should be avoided:
		+
		+	vtkMRMLScalarVolumeNode* vol = vtkMRMLScalarVolumeNode::New();
		+	... do something, such as vol->GetImageData(), someObject->SetVolume(vol)...
		+	vol->Delete();
		+	vol=NULL;
		+
		+	Recommended:
		+
		+	vtkNew<MRMLScalarVolumeNode> vol;
		+	... do something, such as vol->GetImageData(), someObject->SetVolume(vol.GetPointer())...
		+
		+	Also good:
		+
		+	vtkSmartPointer<MRMLScalarVolumeNode> vol=vtkSmartPointer<MRMLScalarVolumeNode>::New();
		+	... do something, such as vol->GetImageData(), someObject->SetVolume(vol)...
		+
		+	vtkNew is preferred in general for new object creation, as it has a simpler syntax and used almost exclusively in the Slicer core source code. A slight inconvenience is that when we need use the GetPointer() method to get the actual pointer value.
		+
		+	A vtkSmartPointer pointer can be created without actually creating an object, so vtkSmartPointer should be used when
		+	* we don't know the exact object type that we want to create at the time of the pointer creation (e.g., we create a vtkSmartPointer<vtkMRMLVolumeNode> and later set it to point to a vtkMRMLScalarVolumeNode or vtkMRMLVectorVolumeNode)
		+	* we need to take the ownership of an already created object (using vtkSmartPointer::Take(...), see a examples below)

	= Factory methods =		= Factory methods =

@@ Line 1: / Line 1: @@
 <noinclude>{{documentation/versioncheck}}</noinclude>
 Similarly to VTK, Slicer contains some "factory" methods:
@@ Line 8: / Line 10: @@
 Factory methods return a pointer to a VTK object (with a reference count of 1) that the caller "owns", so the caller must take care of releasing the object to avoid memory leak.
-= Loadable modules (C++) =
+== Loadable modules (C++) ==
 If storing in a new variable:
@@ Line 24: / Line 26: @@
   nodes->Delete();
-= Python scripts and scripted modules =
+== Python scripts and scripted modules ==
 Factory methods return an object that the caller owns (and thus the caller has to delete, with reference count >0) and Python adds an additional reference to this object when stored in a Python variable, resulting in a reference count of >1. To make sure that the object is deleted when the Python variable is deleted, we have to remove the additional reference that the factory method added. There is currently no automatic mechanism to remove that additional reference, so it has to be done manually by calling UnRegister (the reference count shouldn't be explicitly set to any specific value, it is only allowed to increment/decrement it using Register/UnRegister):

@@ Line 1: / Line 1: @@
 <noinclude>{{documentation/versioncheck}}</noinclude>
-Like VTK, Slicer contains some "factory" methods:
+Similarly to VTK, Slicer contains some "factory" methods:
   - vtkMRMLScene::CreateNodeByClass()
   - vtkMRMLScene::GetNodesByClass()
   - ...
-While there is workaround for some methods (
+Factory methods return a pointer to a VTK object (with a reference count of 1) that the caller "owns", so the caller must take care of releasing the object to avoid memory leak.
-The only "hack" that exists for now is to decrease the reference count
+= Loadable modules (C++) =
-  nodes = slicer.mrmlScene.GetNodesByClass('vtkMRMLLinearTransformNode')
+If storing in a new variable:
- nodes.UnRegister(slicer.mrmlScene)      # ----> (reference count was 2, keep 1 for the python reference)
- ...
+  vtkSmartPointer<vtkCollection> nodes = vtkSmartPointer<vtkCollection>::Take(mrmlScene->GetNodesByClass("vtkMRMLLinearTransformNode"));
-In C++, the following would apply:
+If the variable is created already:
   vtkSmartPointer<vtkCollection> nodes;
   nodes.TakeReference(mrmlScene->GetNodesByClass("vtkMRMLLinearTransformNode"));
   ...
-Amendment from JC http://viewvc.slicer.org/viewvc.cgi/Slicer4?view=revision&revision=19772
+Factory methods return an object that the caller owns (and thus the caller has to delete, with reference count >0) and Python adds an additional reference to this object when stored in a Python variable, resulting in a reference count of >1. To make sure that the object is deleted when the Python variable is deleted, we have to remove the additional reference that the factory method added. There is currently no automatic mechanism to remove that additional reference, so it has to be done manually by calling UnRegister (the reference count shouldn't be explicitly set to any specific value, it is only allowed to increment/decrement it using Register/UnRegister):
-The reference count shouldn't be decreased using the naive approach where
+ nodes = slicer.mrmlScene.GetNodesByClass('vtkMRMLLinearTransformNode')
-it is set to one. Indeed, internally, the reference count could be any
+ nodes.UnRegister(slicer.mrmlScene)  # reference count is increased by both the factory method and the python reference; unregister to keep only the python reference
-number greater than one. It doesn't have to be 2.
+ ...
-Considering this last remark, using the following approach is *REQUIRED*,
+'''To avoid forgetting the UnRegister call, it is better to avoid factory methods whenever it is possible.'''
   n = slicer.mrmlScene.CreateNodeByClass('vtkMRMLViewNode')
   slicer.mrmlScene.addNode(n)
   n.UnRegister(slicer.mrmlScene)
+this should be used (if the name of the node is known when the script is written):
    n = slicer.mrmlScene.addNode(slicer.vtkMRMLViewNode())
+or this should be used (if the name of the node is generated at runtime):
    n = eval('slicer.mrmlScene.AddNode(slicer.%s())' % 'vtkMRMLViewNode')

← Older revision		Revision as of 07:57, 14 June 2013
Line 1:		Line 1:
		+	<noinclude>{{documentation/versioncheck}}</noinclude>
	From http://massmail.spl.harvard.edu/public-archives/slicer-devel/2011/007513.html		From http://massmail.spl.harvard.edu/public-archives/slicer-devel/2011/007513.html