Show
Ignore:
Timestamp:
10/12/09 13:49:39 (15 years ago)
Author:
mido
Message:

\doc directory cleaned a bit

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • library/doc/html/memory_management.html

    r641 r651  
    1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 
    2 <html xmlns="http://www.w3.org/1999/xhtml"> 
    3 <head> 
    4 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> 
     1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 
     2<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8"> 
    53<title>mixpp: Memory Management in BDM</title> 
    6 <link href="tabs.css" rel="stylesheet" type="text/css"/> 
    7 <link href="doxygen.css" rel="stylesheet" type="text/css"/> 
    8 </head> 
    9 <body> 
    10 <!-- Generated by Doxygen 1.6.1 --> 
     4<link href="tabs.css" rel="stylesheet" type="text/css"> 
     5<link href="doxygen.css" rel="stylesheet" type="text/css"> 
     6</head><body> 
     7<!-- Generated by Doxygen 1.5.9 --> 
    118<script type="text/javascript"> 
    129<!-- 
    … …  
    6360</div> 
    6461<div class="contents"> 
    65  
    66  
    67 <h1><a class="anchor" id="memory_management">Memory Management in BDM </a></h1><p>C++ memory management is notoriously flexible, allowing a wide range of efficient and dangerous techniques. BDM uses conventions which allow high implementation efficiency (not absolutely maximal, but within a measurement error of the most efficient way) while substantially reducing the danger of memory errors. These conventions are described below.</p> 
    68 <h2><a class="anchor" id="Constructors"> 
     62<h1><a class="anchor" name="memory_management">Memory Management in BDM </a></h1>C++ memory management is notoriously flexible, allowing a wide range of efficient and dangerous techniques. BDM uses conventions which allow high implementation efficiency (not absolutely maximal, but within a measurement error of the most efficient way) while substantially reducing the danger of memory errors. These conventions are described below.<h2><a class="anchor" name="Constructors"> 
    6963Constructors</a></h2> 
    7064<ul> 
    … …  
    7468<li>Each constructor must initialize all fields of the constructed object, to prevent unpredictable behavior.</li> 
    7569</ul> 
    76 <p>One consequence of the points above is the case when a default constructor doesn't have the data with which to initialize a new object - in that case it can simply call the default constructors of all its object fields (and base classes), but must explicitly initialize all numeric fields and raw pointers to 0. Such an object isn't valid as constructed and must have some additional initialization methods (typically from_settings, for reading its configured state), but it can at least be destroyed.</p> 
    77 <h2><a class="anchor" id="Exceptions"> 
     70One consequence of the points above is the case when a default constructor doesn't have the data with which to initialize a new object - in that case it can simply call the default constructors of all its object fields (and base classes), but must explicitly initialize all numeric fields and raw pointers to 0. Such an object isn't valid as constructed and must have some additional initialization methods (typically from_settings, for reading its configured state), but it can at least be destroyed.<h2><a class="anchor" name="Exceptions"> 
    7871Exceptions</a></h2> 
    79 <p>BDM uses exceptions to signal runtime and some logic errors. The library aims to provide the minimal exception safety (that is, throwing an exception doesn't crash and doesn't leak any resources) for all thrown exceptions <b>except</b> memory errors - when a program using BDM exhausts memory, it should be terminated as soon as possible (and in most cases it has probably already terminated by itself). Specific exceptions may provide stronger guarantees, as documented for specific cases. All exceptions thrown out of the library are descendants of std::exception. Since they're organized into a class hierarchy, they should be caught by reference:</p> 
     72BDM uses exceptions to signal runtime and some logic errors. The library aims to provide the minimal exception safety (that is, throwing an exception doesn't crash and doesn't leak any resources) for all thrown exceptions <b>except</b> memory errors - when a program using BDM exhausts memory, it should be terminated as soon as possible (and in most cases it has probably already terminated by itself). Specific exceptions may provide stronger guarantees, as documented for specific cases. All exceptions thrown out of the library are descendants of std::exception. Since they're organized into a class hierarchy, they should be caught by reference:<p> 
    8073<div class="fragment"><pre class="fragment"><span class="keywordflow">try</span> { 
    8174        mpdf* mtmp = UI::build&lt;mpdf&gt; (_Sources, i); 
    8275        Sources (i) = mtmp; 
    8376} <span class="keywordflow">catch</span> (UIException &amp;exc) { 
    84 </pre></div><p>This saves one call to copy constructor and prevents slicing.</p> 
    85 <h2><a class="anchor" id="Pointers"> 
     77</pre></div><p> 
     78This saves one call to copy constructor and prevents slicing.<h2><a class="anchor" name="Pointers"> 
    8679Pointers</a></h2> 
    87 <p>Pointers are used extensively (for efficiency), but usage of raw pointers should be minimized.</p> 
    88 <p>Objects allocated by operator new should be assigned to a smart pointer instance immediately upon their construction, so that they can be automatically deleted after use. BDM implements its own reference-counted smart pointer template, <a class="el" href="classbdm_1_1shared__ptr.html" title="A naive implementation of roughly a subset of the std::tr1::shared_ptr spec.">bdm::shared_ptr</a>, whose interface and semantics are close to the proposed standard std::tr1:shared_ptr (which is planned to replace <a class="el" href="classbdm_1_1shared__ptr.html" title="A naive implementation of roughly a subset of the std::tr1::shared_ptr spec.">bdm::shared_ptr</a> once it becomes widely available). Note that objects allocated on the stack <b>must</b> <b>not</b> have their addresses passed to shared_ptr - that is a bug leading to intermittent runtime errors.</p> 
    89 <p>Non-null heap pointers may also be kept in instances of object_ptr, which is convertible to (and from) shared_ptr. The SHAREDPTR macro (or SHAREDPTR2, for templated types) defines standartized names for these instances, simplifying library usage:</p> 
     80Pointers are used extensively (for efficiency), but usage of raw pointers should be minimized.<p> 
     81Objects allocated by operator new should be assigned to a smart pointer instance immediately upon their construction, so that they can be automatically deleted after use. BDM implements its own reference-counted smart pointer template, <a class="el" href="classbdm_1_1shared__ptr.html" title="A naive implementation of roughly a subset of the std::tr1::shared_ptr spec.">bdm::shared_ptr</a>, whose interface and semantics are close to the proposed standard std::tr1:shared_ptr (which is planned to replace <a class="el" href="classbdm_1_1shared__ptr.html" title="A naive implementation of roughly a subset of the std::tr1::shared_ptr spec.">bdm::shared_ptr</a> once it becomes widely available). Note that objects allocated on the stack <b>must</b> <b>not</b> have their addresses passed to shared_ptr - that is a bug leading to intermittent runtime errors.<p> 
     82Non-null heap pointers may also be kept in instances of object_ptr, which is convertible to (and from) shared_ptr. The SHAREDPTR macro (or SHAREDPTR2, for templated types) defines standartized names for these instances, simplifying library usage:<p> 
    9083<div class="fragment"><pre class="fragment"><span class="comment">/*</span> 
    9184<span class="comment"> egamma_ptr is typedef for object_ptr&lt;egamma&gt;, whose default</span> 
    … …  
    9992 
    10093<span class="comment">/*</span> 
    101 <span class="comment"> The egamma instance doesn&apos;t leak: if the shared_ptr instance which</span> 
    102 <span class="comment"> wraps it isn&apos;t assigned to anything else, the pointer is deleted by</span> 
     94<span class="comment"> The egamma instance doesn't leak: if the shared_ptr instance which</span> 
     95<span class="comment"> wraps it isn't assigned to anything else, the pointer is deleted by</span> 
    10396<span class="comment"> the destructor of either object_ptr, or Array, whichever runs last.</span> 
    10497<span class="comment">*/</span> 
    105 </pre></div><p>Pointers kept in object fields should be wrapped in a shared_ptr instance, which will automatically keep them valid (at least) for the lifetime of the containing object. When that isn't possible, it should be documented why their containing class doesn't delete them and who does.</p> 
    106 <p>Pointers passed as arguments into functions (and methods) are generally not expected to stay valid after the function returns - when that is required, the parameter's documentation should specify the required scope:</p> 
     98</pre></div><p> 
     99Pointers kept in object fields should be wrapped in a shared_ptr instance, which will automatically keep them valid (at least) for the lifetime of the containing object. When that isn't possible, it should be documented why their containing class doesn't delete them and who does.<p> 
     100Pointers passed as arguments into functions (and methods) are generally not expected to stay valid after the function returns - when that is required, the parameter's documentation should specify the required scope:<p> 
    107101<div class="fragment"><pre class="fragment"><span class="comment">/* the pointer must stay valid for the lifetime of the object */</span> 
    108102CurrentContext ( <span class="keyword">const</span> <span class="keywordtype">char</span> *name, <span class="keywordtype">int</span> idx ); 
    109 </pre></div><p>A simpler alternative is just to pass a shared pointer:</p> 
     103</pre></div><p> 
     104A simpler alternative is just to pass a shared pointer:<p> 
    110105<div class="fragment"><pre class="fragment"><span class="keyword">class </span>mepdf : <span class="keyword">public</span> mpdf 
    111106{ 
    … …  
    114109        mepdf (shared_ptr&lt;epdf&gt; em) { 
    115110                iepdf = em; 
    116 </pre></div><p>In the case above, passing a (constant) reference to <a class="el" href="classbdm_1_1shared__ptr.html">shared_ptr&lt;epdf&gt;</a> might be more efficient, but no measurements have been performed.</p> 
    117 <p>Functions returning raw pointers should document the scope of their validity:</p> 
     111</pre></div><p> 
     112In the case above, passing a (constant) reference to <a class="el" href="classbdm_1_1shared__ptr.html">shared_ptr&lt;epdf&gt;</a> might be more efficient, but no measurements have been performed.<p> 
     113Functions returning raw pointers should document the scope of their validity:<p> 
    118114<div class="fragment"><pre class="fragment"><span class="comment">/*</span> 
    119115<span class="comment"> Returns the stored pointer (which remains owned by this</span> 
    … …  
    121117<span class="comment">*/</span> 
    122118T *<span class="keyword">get</span>(); 
    123 </pre></div><p>Functions generally shouldn't return raw pointers allocated by operator new - such pointers should be wrapped in an instance of shared_ptr, so that the pointer's unlimited life expectancy is encoded in the function signature:</p> 
     119</pre></div><p> 
     120Functions generally shouldn't return raw pointers allocated by operator new - such pointers should be wrapped in an instance of shared_ptr, so that the pointer's unlimited life expectancy is encoded in the function signature:<p> 
    124121<div class="fragment"><pre class="fragment"><span class="keyword">virtual</span> shared_ptr&lt;epdf&gt; marginal (<span class="keyword">const</span> RV &amp;rv) <span class="keyword">const</span>; 
    125122</pre></div> </div> 
    126 <hr size="1"/><address style="text-align: right;"><small>Generated on Sun Sep 27 00:49:05 2009 for mixpp by&nbsp; 
     123<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 7 17:34:45 2009 for mixpp by&nbsp; 
    127124<a href="http://www.doxygen.org/index.html"> 
    128 <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.1 </small></address> 
     125<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.9 </small></address> 
    129126</body> 
    130127</html>