root/library/doc/tutorial/memory_management.dox @ 680

/*!
\page memory_management Memory Management in BDM

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.

\section Constructors

\li Each configurable class must have public default constructor (that
is, a constructor which takes no parameters). This is required by the
configuration framework. Other constructors may also be defined when
convenient.

\li Each constructor must initialize all fields of the constructed
object, to prevent unpredictable behavior.

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.

\section Exceptions

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 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:

\code
try {
        mpdf* mtmp = UI::build<mpdf> (_Sources, i);
        Sources (i) = mtmp;
} catch (UIException &exc) {
\endcode

This saves one call to copy constructor and prevents slicing.

\section Pointers

Pointers are used extensively (for efficiency), but usage of raw
pointers should be minimized.

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, bdm::shared_ptr, whose
interface and semantics are close to the proposed standard
std::tr1:shared_ptr (which is planned to replace bdm::shared_ptr once
it becomes widely available). Note that objects allocated on the stack
\b must \b not have their addresses passed to shared_ptr - that is a
bug leading to intermittent runtime errors.

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:

\code
/*
 egamma_ptr is typedef for object_ptr<egamma>, whose default
 constructor calls new egamma()
*/
egamma_ptr eG; 
eG->set_parameters ( a, b );

epdf_array Coms ( 2 ); // epdf_array is typedef for Array<shared_ptr<epdf> >
Coms ( 0 ) = eG; // object_ptr<T> is derived from shared_ptr<T>

/*
 The egamma instance doesn't leak: if the shared_ptr instance which
 wraps it isn't assigned to anything else, the pointer is deleted by
 the destructor of either object_ptr, or Array, whichever runs last.
*/
\endcode

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.

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:

\code
/* the pointer must stay valid for the lifetime of the object */
CurrentContext ( const char *name, int idx );
\endcode

A simpler alternative is just to pass a shared pointer:

\code
class mepdf : public mpdf
{
        shared_ptr<epdf> iepdf;
public:
        mepdf (shared_ptr<epdf> em) {
                iepdf = em;
\endcode

In the case above, passing a (constant) reference to shared_ptr<epdf>
might be more efficient, but no measurements have been performed.

Functions returning raw pointers should document the scope of their
validity:

\code
/*
 Returns the stored pointer (which remains owned by this
 instance).
*/
T *get();
\endcode

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:

\code
virtual shared_ptr<epdf> marginal (const RV &rv) const;
\endcode

*/