Main Lemma Repository

mem.dox 4.6KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101
  1. namespace Lemma{
  2. /**
  3. \page Memory
  4. <div class="lemmamainmenu">
  5. \ref Intro "Intro"
  6. | \ref Compiling "Compiling"
  7. | \b Memory \b management
  8. | \ref Minimal "Minimal programme"
  9. | \ref EmSources "EM Sources"
  10. </div>
  11. \section MemoryManagement Memory Management
  12. \subsection Reference Reference counting and memory management
  13. Lemma makes extensive use of reference counting. We do this for a variety of
  14. reasons.
  15. - It is not uncommon for multiple objects to have the same instantiations
  16. of an object as members.
  17. - Making copies of each object is not a viable option because the objects may be large, and they must all update simultaneously.
  18. - Without reference counting it is very easy to leave dangling pointers.
  19. - It is much easier to write code, as local copies of objects can be deleted
  20. as soon as they are no longer used within that context. The memory will not be
  21. freed and the object persists as long as other objects still reference it.
  22. The base class for all Lemma objects is ReferenceCountedObject.
  23. The interface requires that all derived, non-abstract classes have <B>New</B> and <B>Delete</B> methods. So that objects may be created and destoyed with the
  24. following syntax.
  25. \code
  26. DerivedClass* Object = DerivedClass::New();
  27. Object->Delete();
  28. \endcode
  29. \warning It is important to note that the default constructors and destructors are protected so the following code is <B>NOT</B> valid.
  30. \code
  31. DerivedClass* Object = new DerivedClass;
  32. delete Object;
  33. \endcode
  34. The reasons for this will hopefully be clear soon.
  35. Many Lemma classes have other Lemma classes as data members. Classes may
  36. share these members, and depend on them being updated simultaneously. So
  37. that a situation like this is not unusual.
  38. \code
  39. DerivedClass* Component = DerivedClass::New();
  40. AnotherDerivedClass* Object2 = AnotherDerivedClass::New();
  41. YetAnotherDerivedClass* Object3 = YetAnotherDerivedClass::New();
  42. Object2->AttachMyComponent(Component);
  43. Object3->AttachMyComponent(Component);
  44. Component->Update(); // All three classes use the updated Component
  45. \endcode
  46. At this point both Object2 and Object3 have an up to date Component and any
  47. changes to Component can be seen by the Objects. Often these types of
  48. connections are happening behind the scenes and end users should not be
  49. troubled by any of this.
  50. Now in this example it is clear that if Component is deleted, than the objects
  51. will contain dangling pointers. To avert this, calling the
  52. ReferenceCountedObject::Delete() does not necessarily destroy the object.
  53. So that it would be safe -- continuing from the above example
  54. \code
  55. Component->Delete(); // The 'Component' handle will no longer be used.
  56. Object2->CallMethodRelyingOnComponent(); // But we can still use the object
  57. \endcode
  58. \subsection what Whats going on?
  59. Whenever we declared a new handle to the object-- either by calling New, or implicitly in the Connect methods--
  60. the true 'Component' object updated a list of pointers that had handles to it.
  61. \code
  62. DerivedClass* Component = DerivedClass::New(); // One Reference, 'Component'
  63. Object2->AttachMyComponent(Component); // Two References, internal in Object2
  64. Object3->AttachMyComponent(Component); // Three References, internal in Object3
  65. Component->Delete(); // Two References, 'Component' is gone.
  66. // DON'T USE Component->Method() ANYMORE!!!
  67. Object2->Delete(); // One Reference, Object2 releases handle upon Delete
  68. Object3->SomeFuntionReleasingComponent(); // Zero References, Component object is now deleted and
  69. // all memory is freed!
  70. \endcode
  71. \section So So what do I need to know?
  72. Not much. This is here to make life easy when doing high level programming. Just follow these simple rules
  73. - Allocate and free all variables with New and Delete, you have to do this as the default
  74. versions are protected.
  75. - Once calling Delete on an object it is no longer safe to use that handle. For example don't call
  76. Component->Delete(), and then call Component->Method(). Even if you 'know' that there are existing references
  77. and that it shouldn't have been deleted yet. Instead move your call to Delete down after your last direct use
  78. of each class.
  79. - Remember to call Delete, thanks to reference counting it is safe to do this as soon as you are done
  80. using an object even if other classes are using it. If you don't call Delete on objects you create, your
  81. program <B>will</B> leak memory!
  82. - Revel in the fact that memory is being managed for you, and that dangling pointers are not a concern.
  83. */
  84. }