CoCoALib-0.9905 date: 23 May 2007


CoCoA::SmartPtrIRC< T > Class Template Reference

#include <SmartPtrIRC.H>

List of all members.

Public Member Functions

 SmartPtrIRC (T *RawPtr)
 SmartPtrIRC (const SmartPtrIRC< T > &ToBeCopied)
 ~SmartPtrIRC ()
T * myRawPtr () const
 to avoid too many friend stmts
T * operator-> () const
 allow const member fns to be called


Detailed Description

template<typename T>
class CoCoA::SmartPtrIRC< T >

      Copyright (c)  2006 John Abbott
      Permission is granted to copy, distribute and/or modify this document
      under the terms of the GNU Free Documentation License, Version 1.2;
      with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
      A copy of the licence is included in the file COPYING in this directory.



User documentation for files SmartPtrIRC
========================================

The name [SmartPtrIRC] stands for "smart pointer with intrusive
reference count".  The desired behaviour is achieved through two cooperating classes:
[SmartPtrIRC] and [IntrusiveReferenceCount].  These classes exist to facilitate implementation of
smart pointers with reference counting.  The suggested use is as follows.
Make your implementation class inherit [protected]-ly from
[IntrusiveReferenceCount], and in your implementation class declare the
class [SmartPtrIRC<MyClass>] as a friend.  You can now use the class
[SmartPtrIRC<MyClass>] as a reference counting smart pointer to your class.

The template argument of the class [SmartPtrIRC] specifies the type of
object pointed to; if you want the objects pointed at to be [const] then
put the keyword "const" in the template argument like this
[SmartPtrIRC<const MyClass>].  Creating a new [SmartPtrIRC] to a datum will
increment its reference count; conversely, destroying the [SmartPtrIRC]
decrements the ref count (and destroys the object pointed at if the ref
count reaches zero, see [IntrusiveReferenceCount::myRefCountDec]).  Three
operations are available for [SmartPtrIRC] values:

  let [SPtr] be a [SmartPtrIRC] value
  SPtr.myRawPtr()   -- returns the equivalent raw pointer
  SPtr.operator->() -- returns the equivalent raw pointer
  SPtr1 == SPtr2    -- returns true iff the equivalent raw pointers are equal


The class [IntrusiveReferenceCount] is intended to be used solely as a base
class.  Note the existence of [IntrusiveReferenceCount::myRefCountZero] which
forces the reference count to be zero.  For instance, this is used in ring
implementations where the ring object contains some "circular" references to
itself; after creating the circular references the ring constructor then
resets the reference count to zero so that the ring is destroyed as the right
moment.  SEE BUGS SECTION.

IMPORTANT NOTE: it is highly advisable to have [myRefCountZero()] as the very
last operation in every contructor of a class derived from
[IntrusiveReferenceCount], i.e. intended to be used with [SmartPtrIRC].


Maintainer documentation for files SmartPtrIRC
==============================================

The entire implementation is in the ".H" file: a template class, and
another class with only inline member functions.  Inlining is appropriate
as the functions are extremely simple and we expect them to be called a
very large number of times.

The implementation is quite straightforward with one important detail: the
destructor of [IntrusiveReferenceCount] must be virtual because
[myRefCountDec] does a "polymorphic delete" through a pointer to
[IntrusiveReferenceCount] when the count drops to zero.  The book by Sutter
and Alexandrescu gives wrong advice (in article 50) about when to make
destructors virtual!


Bugs, Shortcomings and other ideas
==================================

Should [myRefCountZero] be eliminated?  It is not strictly necessary (just call
[myRefCountDec] after each operation which incremented the ref count.  This is
related to how rings create their zero and one elements (and possibly other
elements which should "always exist", e.g. indets in a poly ring).

Could ref count overflow?  Perhaps size_t is always big enough to avoid overflow?

It may be possible to replace all this code with equivalent code from the BOOST library.
But so far (Nov 2006) the [shared_ptr] implementation in BOOST is not documented, so
presumably should not be used.  As there is no documentation I have not verified the
existence of a "set ref count to zero" function; I rather suspect that it does not exist.

=============================================================================

Definition at line 34 of file SmartPtrIRC.H.


Constructor & Destructor Documentation

template<typename T>
CoCoA::SmartPtrIRC< T >::SmartPtrIRC T *  RawPtr  )  [inline, explicit]
 

Definition at line 37 of file SmartPtrIRC.H.

template<typename T>
CoCoA::SmartPtrIRC< T >::SmartPtrIRC const SmartPtrIRC< T > &  ToBeCopied  )  [inline]
 

Definition at line 39 of file SmartPtrIRC.H.

template<typename T>
CoCoA::SmartPtrIRC< T >::~SmartPtrIRC  )  [inline]
 

Definition at line 40 of file SmartPtrIRC.H.


Member Function Documentation

template<typename T>
T* CoCoA::SmartPtrIRC< T >::myRawPtr  )  const [inline]
 

to avoid too many friend stmts

Definition at line 44 of file SmartPtrIRC.H.

Referenced by CoCoA::ServerOp::myRawPtr(), CoCoA::ring::myRawPtr(), CoCoA::PPOrdering::myRawPtr(), CoCoA::OrdvArith::reference::myRawPtr(), CoCoA::ModuleTermOrdering::myRawPtr(), CoCoA::module::myRawPtr(), and CoCoA::operator==().

template<typename T>
T* CoCoA::SmartPtrIRC< T >::operator->  )  const [inline]
 

allow const member fns to be called

Definition at line 45 of file SmartPtrIRC.H.


The documentation for this class was generated from the following file:
Generated on Wed May 23 13:46:31 2007 for CoCoALib by  doxygen 1.4.6