COWPtr.h

Go to the documentation of this file.

//# COWPtr.h: this defines the Copy-On-Write-Pointer class.
//# Copyright (C) 1996,1997,1999
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library is distributed in the hope that it will be useful, but WITHOUT
//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
//# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//#        Internet email: aips2-request@nrao.edu.
//#        Postal address: AIPS++ Project Office
//#                        National Radio Astronomy Observatory
//#                        520 Edgemont Road
//#                        Charlottesville, VA 22903-2475 USA
//#
//#
//# $Id$
 
#ifndef CASA_COWPTR_H
#define CASA_COWPTR_H
 
#include <casacore/casa/aips.h>
#include <casacore/casa/Utilities/CountedPtr.h>
 
namespace casacore { //# NAMESPACE CASACORE - BEGIN
 
// <summary>
// Copy-On-Write-Pointer class - allows control of copy based on constness.
// </summary>
 
// <use visibility=export>
 
// <reviewed reviewer="Ger van Diepen" date="1996/02/21" tests="tCOWPtr.cc" demos="">
// </reviewed>
 
// <prerequisite>
//   <li> none
// </prerequisite>
//
// <etymology>
// The COWPtr class name is a contraction of Copy-On-Write-Pointer 
// and is a reflection of its role as a carrier of objects which need to 
// minimize their copying and control their destruction.  Such objects only 
// need to copy if written to.
// </etymology>
//
// <synopsis>
// COWPtr can be used by other classes to implement copy-on-write
// semantics. Copy-on-write means that a copy of an object is not
// made until necessary. A well-known example is a String class
// with internally a pointer to a StringRep containing the true string.
// When a copy of a String is made, the StringRep is not copied yet.
// Only when the String gets changed and when more than one String
// points to the same StringRep, a copy of the StringRep is made.
// This technique can prevent a lot of copying when arguments are
// passed by value.
//<br>
// Implementing a String in this way is straightforward when
// String defines the pointer to its StringRep as <src>COWPtr<StringRep></src>
// and uses the appropriate functions (ref() and rwRef()) to execute
// const and non-const StringRep functions.
//<br>
// An example of this (straightforward) usage is class
//    <linkto class=RecordDesc>RecordDesc</linkto>.
//<p>
// COWPtr offers possibilities for more advanced usage:
// <ul>
// <li> Normally a copy (on write) is made when more than one String points to
//      the same StringRep. By constructing the COWPtr object with
//      readOnly=True, it is possible to already do that when only one
//      String points to a StringRep. This can be used when a function
//      returns an object referencing a constant object. For instance,
//      a function can return an Array object referencing another Array
//      which should not be altered.
//      By returning a <src>COWPtr<Array></src> with readOnly=True,
//      it is assured that a copy is made as soon as somebody wants
//      to change the returned Array object. No (expensive) copy is
//      made when only const access is being done.
// <li> Normally the COWPtr object takes over the pointer and deletes
//      the underlying object when it is not used anymore. With the
//      deleteIt flag it is possible to change this behavior.
//</ul>
//<p>
// Apart from the fact that COWPtr handles the copying, it has
// the big advantage that it forces that its access functions (ref and
// rwRef) are used in the correct way (ie. ref() for a const
// function and rwRef() for a non-const function). This ensures that
// copies are made when needed and not made when not needed.
//<p>
// Note that COWPtr uses the default constructor and the assignment
// operator to make a copy (thus not the copy constructor). The
// reason for this is that the copy constructor of some classes
// (e.g. Array) has reference semantics iso. copy semantics.
// </synopsis>
//
// <example>
// <h4>Example 1:</h4>
// <srcblock>
//    class String {
//    public:
//  // The constructor allocates a StringRep and hands to pointer
//  // to COWPtr.
//        String()
//        : itsRep (new StringRep;) {}
//        // This non-const function needs rwRef to make a copy when needed.
//        void set (const char* str) {itsRep.rwRef().set (str);}
//        // This const function can use ref (making a copy is not needed).
//        const char* get const {return itsRep.ref();}
//    private:
//        COWPtr<StringRep> itsRep;
//    };
//    class StringRep {
//    friend class String;
//    private:
//        void set (const char*);
//        const char* get() const;
//  char* itsData;
//    };
//</srcblock>
// <h4>Example 2:</h4>
// This function requires a const Array be passed out from the local scope.  
// The Array is created with non-const functions out of necessity (i.e. no
// const versions of the Array::getSlice() function exist.)  Preventing
// copies of the Array from being made forces us to use a COWPtr.  The COWPtr
// has arguments which allow us to declare the Array as const and not make
// any copies until a write operation is performed.
// <srcblock> 
// void myFunc(COWPtr<Array<Float> > &obj){
// // make a nonconst from some static const Array that exists "out there"
// Array<Float> &nonConstArray = (Array<Float> &)staticConstArray;
// // "fill" the COWPtr and bring back constness without copying. The first
// // "True" argument indicates the caller of this function may take
// // control of the dynamic pointer's destruction.  The second "True"
// // argument indicates the array is read only and should make a copy of 
// // itself if writing is needed.
// obj.set(new Array<Float>(nonConstArray.getSlice(...), True, True));
// }
// </srcblock>
// The caller of the function will get their piece of a const array without
// making a copy until the last possible moment (maybe never.)
// <srcblock>
// #include <casacore/casa/Utilities/COWPtr.h>
// main(){
//   // create a null filled COWPtr
//   COWPtr<Array<Float> > COW;
//   // fill it inside myfunc
//   myFunc(COW);
//   // use a single element - still no copies have been made!
//   Float someVal = COW->operator()(IPosition(2,3,3))
//   // write to the array - now we get a copy!
//   COW.rwRef().set(42.0f);
//   // etc...
// };
// </srcblock>
// </example>
//
// <motivation>
// Three words; efficiency, efficiency, efficiency.  Not everything may be
// passed as a reference.  With COWPtrs we may fake it.
// </motivation>
//
// <templating arg=T>
//    <li> default constructor
//    <li> assignment operator
// </templating>
//
// <thrown>
//    <li> AipsError
// </thrown>
//
// <todo asof="1996/01/16">
// <li> none
// </todo>
 
template <class T> class COWPtr
{
public:
  
  // The default constructor: used to create a null pointer which is 
  // delete-able by the destructor.  It is not "readOnly" so that it may be
  // changed by the COWPtr<T>::set() function.
  inline COWPtr(); 
  
  // The dynamic "pointer to object" constructor: default behavior is to 
  // delete the allocated memory when this instance's of COWPtr is destructed. 
  // Or the Boolean argument of "deleteIt = False" implies the pointer is 
  // being maintained by an object other than this instance of COWPtr and 
  // will not delete the allocated memory upon this instance's destruction. 
  // Control of copying is provided by the Boolean "readOnly" argument.  The
  // default value of "readOnly = False" forces a copy