source: ThirdParty/mpqc_open/src/lib/util/ref/ref.dox@ b10593

/** \page ref The Reference Library

The Reference Library provides a means to automatically free
memory that is no longer needed.

<ul>
  <li> \ref refintro
  <li> \ref refthread
  <li> \ref refcust
  <li> \ref refexample
</ul>

\section refintro Introduction to Reference Counting

It is fairly easy in C++ to create a pointer to an object that
actually references invalid memory.  One common way to do this
is to create an object with new and store that
object's pointer.  Then the pointer is given to another
object's member function as an argument which keeps a copy of
the pointer for future use.  After the member function
returns, the routine that originally created the object
delete's it, not knowing that another object has since
created a reference to the object.  The result of using the
delete'ed object is unpredictable and would likely be
a program crash.  It is up to the programmer to provide the
logic necessary to avoid this problem.  The programmer must
also deal with the problem of calling to delete
operator on any new'ed memory when it is no longer
referenced.

Reference counting is one technique that can be applied to
automate memory management.  In this approach, a count of how
many pointers point to an object is attached to that object.
This count is managed by a smart pointer class which mimics
the behavior of C++ pointers by providing
<tt>operator->()</tt>.  This class has a pointer to the
reference counted object and increments the reference count of
objects when they are assigned to it while decrementing the
counts of the objects that are displaced by these assigments.
The smart pointer class automatically delete's the
object when its reference count drops to zero.

A deficiency of this method is that unreferenced circular
lists are not automatically deleted.  Circular list
implementors must provide a mechanism to detect when the list
is dereferenced and then break the list's circularity to let
the automated reference mechanism finish the work.

The reference library provides smart pointers and a base class that
can be used to maintain reference counts to objects.  For an
object to be reference counted its class must inherit from
the RefCount class.  This adds <tt>sizeof(int)</tt> bytes
of overhead per object and makes the destructor virtual (so a vtable
will be added to objects of the class, if there wasn't already a virtual
member in the class).

The smart pointers that maintain the reference counts are
provided by the Ref class template.  A smart pointer to a
class A which inherits from RefCount would have the
type Ref<A>.

\section refthread Thread Safety of the Reference Counting Package

The referencing counting package is thread-safe if the CPP macro
REF_USE_LOCKS is defined to 1.  This means that Ref's to a particular
object can be created and reassigned and destroyed in different
threads.  However, the Ref's themselves are not thread-safe.
For example, a static Ref cannot be simultaneously modified from
multiple threads.

Because there is an overhead associated with locking access to an
object's reference count, locking is not turned on by default,
and, thus, making and deleting references to an object in
multiple threads is not thread-safe by default.  The
RefCount::use_locks member is passed a bool value to turn locking
on and off on a per object basis.

\section refcust Customizing the Reference Counting Package

  The behaviour of the package can be modified at compile time
with the following five macros, each of which should be undefined, 0, or 1:

<dl>
<dt><tt>REF_CHECK_STACK</tt><dd>
  If this is 1, referenced objects are checked to see if they
  reside on the stack, in which case storage for the object is not managed,
  if management is enabled.
<dt><tt>REF_MANAGE</tt><dd>
  If this is 1, the unmanage member is enabled.
<dt><tt>REF_CHECK_MAX_NREF</tt><dd>
  If this is 1, the reference count is checked before
  it is incremented to make sure it isn't too big.
<dt><tt>REF_CHECK_MIN_NREF</tt><dd>
  If this is 1, the reference count is checked before
  it is decremented to make sure it isn't already zero.
<dt><tt>REF_USE_LOCKS</tt><dd>
  If this is 1, modification of the reference count
  is locked to allow thread-safe execution.
</dl>

If a macro is undefined, then the behaviour is architecture
dependent---usually, the macro will be set to 1 in this case.
For maximum efficiency and for normal operation after the program is
debugged, compile with all of the above macros defined to zero.
This can also be done by defining REF_OPTIMIZE.

  An include file can be used to set these options as well.  This has
the advantage that dependency checking will force an automatic
recompile of all affected files if the options change.  This is done
in the file scconfig.h, which is produced by the automated configuration
procedure.

  Note that all source code that uses references must be compiled with
the same value for REF_MANAGE.
Changing this can change the storage layout and the interpretation of
the reference count data.

\section refexample A Reference Example

Following is a simple example of how to manage memory with reference
counts.

<pre>
\#include <util/container/ref.h>

class A: virtual public RefCount {};

class B: public A {};

int
main()
{
  Ref\<A\> a1(new A);
  Ref\<A\> a2;

  // Create another reference to the A object pointed to by a1.
  a2 = a1;

  // Make a2 refer to a new A object.
  a2 = new A;

  // a2 was the only reference to the second A object, so setting
  // a2 to the null object will cause the second A object to be
  // deleted.
  a2 = 0;

  Ref\<B\> b(new B);

  // An object of type Ref\<X\> can be assigned to an object of type
  // Ref\<Y\> as long as X* can be assigned to Y*.
  a1 = b;

  // An automatic dynamic cast can be done by using the left shift
  // operator.
  b << a1;

  // The B object will be deleted here because all of the references
  // to it go out of scope and destroyed.
  return 0;
}
</pre>

*/