casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
Public Member Functions | Protected Attributes
casa::COWPtr< T > Class Template Reference

Copy-On-Write-Pointer class - allows control of copy based on constness. More...

#include <COWPtr.h>

List of all members.

Public Member Functions

 COWPtr ()
 The default constructor: used to create a null pointer which is delete-able by the destructor.
 COWPtr (T *obj, Bool deleteIt=True, Bool readOnly=False)
 The dynamic "pointer to object" constructor: default behavior is to delete the allocated memory when this instance's of COWPtr is destructed.
 COWPtr (const COWPtr< T > &other)
 copy ctor with reference semantics
COWPtroperator= (const COWPtr< T > &other)
 assignment operator with reference semantics
const T * operator-> () const
 return a pointer to a const object.
const T & operator* () const
 return a reference to a const object.
void set (T *obj, Bool deleteIt=True, Bool readOnly=False)
 Function used to change this instance of COWPtr.
void setReadOnly (const T *obj)
void setReadOnly ()
const T & ref () const
 return a const reference to the object.
T & rwRef ()
 return a readable and writable reference to this instance.
Bool isNull () const
 returns False if this contains a non-null ptr, otherwise, return True.
Bool isReadOnly () const
 returns True if the object is const, otherwise, return False.
Bool isUnique () const
 returns True if the object is the only instance, otherwise, return False.
Bool makeUnique ()
 Return True if copied, otherwise, False.

Protected Attributes

CountedPtr< T > obj_p
Bool const_p

Detailed Description

template<class T>
class casa::COWPtr< T >

Copy-On-Write-Pointer class - allows control of copy based on constness.

Intended use:

Public interface

Review Status

Reviewed By:
Ger van Diepen
Date Reviewed:
1996/02/21
Test programs:
tCOWPtr

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.

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.
Implementing a String in this way is straightforward when String defines the pointer to its StringRep as COWPtr<StringRep> and uses the appropriate functions (ref() and rwRef()) to execute const and non-const StringRep functions.
An example of this (straightforward) usage is class RecordDesc .

COWPtr offers possibilities for more advanced usage:

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.

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.

Example

Example 1:

       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;
       };

Example 2:

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.

    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));
    }

The caller of the function will get their piece of a const array without making a copy until the last possible moment (maybe never.)

    #include <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..\.
    };

Motivation

Three words; efficiency, efficiency, efficiency. Not everything may be passed as a reference. With COWPtrs we may fake it.

Template Type Argument Requirements (T)

Thrown Exceptions

To Do

Definition at line 185 of file COWPtr.h.


Constructor & Destructor Documentation

template<class T >
casa::COWPtr< T >::COWPtr ( ) [inline]

The default constructor: used to create a null pointer which is delete-able by the destructor.

Make our own default pointer - deleteIt==True by default, const_p==False.

It is not "readOnly" so that it may be changed by the COWPtr<T>::set() function.

does nothing

Definition at line 274 of file COWPtr.h.

template<class T>
casa::COWPtr< T >::COWPtr ( T *  obj,
Bool  deleteIt = True,
Bool  readOnly = False 
) [explicit]

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 if the number of references to the dynamic memory is greater than one. Copying is always done if the constructor is given an argument of "readOnly = True".
Note: The only copying done (if ever) is upon a call to COWPtr<T>::rwRef();

template<class T>
casa::COWPtr< T >::COWPtr ( const COWPtr< T > &  other) [inline]

copy ctor with reference semantics

does nothing

Definition at line 281 of file COWPtr.h.


Member Function Documentation

template<class T >
Bool casa::COWPtr< T >::isNull ( ) const [inline]

returns False if this contains a non-null ptr, otherwise, return True.

Definition at line 329 of file COWPtr.h.

template<class T >
Bool casa::COWPtr< T >::isReadOnly ( ) const [inline]

returns True if the object is const, otherwise, return False.

Definition at line 334 of file COWPtr.h.

template<class T >
Bool casa::COWPtr< T >::isUnique ( ) const [inline]

returns True if the object is the only instance, otherwise, return False.

Definition at line 339 of file COWPtr.h.

References casa::False, and casa::True.

template<class T>
Bool casa::COWPtr< T >::makeUnique ( )

Return True if copied, otherwise, False.

This function will make this instance's object a copy if it is constructed with "readOnly = True." Additionally, all instances of COWPtr with more than one reference to the allocated memory stored within will be copied.

template<class T >
const T & casa::COWPtr< T >::operator* ( ) const [inline]

return a reference to a const object.

This prevents "write" operations.

Definition at line 313 of file COWPtr.h.

template<class T >
const T * casa::COWPtr< T >::operator-> ( ) const [inline]

return a pointer to a const object.

This prevents "write" operations.

Definition at line 308 of file COWPtr.h.

template<class T>
COWPtr< T > & casa::COWPtr< T >::operator= ( const COWPtr< T > &  other) [inline]

assignment operator with reference semantics

Definition at line 289 of file COWPtr.h.

References casa::COWPtr< T >::const_p, and casa::COWPtr< T >::obj_p.

template<class T >
const T & casa::COWPtr< T >::ref ( ) const [inline]
template<class T >
T & casa::COWPtr< T >::rwRef ( ) [inline]

return a readable and writable reference to this instance.

Instances of COWPtr constructed with argument "readOnly = True" will be made a copy. Additionally, all instances of COWPtr with more than one reference to the allocated memory stored within will be copied.

Definition at line 323 of file COWPtr.h.

Referenced by casa::RecordDesc::addField(), casa::RecordDesc::addTable(), casa::RecordDesc::merge(), casa::RecordDesc::mergeField(), casa::RecordDesc::removeField(), casa::RecordDesc::renameField(), casa::RecordDesc::rwSubRecord(), casa::RecordDesc::setComment(), and casa::RecordDesc::setShape().

template<class T>
void casa::COWPtr< T >::set ( T *  obj,
Bool  deleteIt = True,
Bool  readOnly = False 
)

Function used to change this instance of COWPtr.

The pointer must be dynamically allocated. 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 if the number of references to the dynamic memory is greater than one. Copying is always done if the constructor is given an argument of "readOnly = True".
Note: The only copying done (if ever) is upon a call to COWPtr<T>::rwRef();
The setReadOnly function is the same as set, but forces deleteIt=False and ReadOnly=True. In that way a const object can also be safely referenced by COWPtr.

template<class T>
void casa::COWPtr< T >::setReadOnly ( const T *  obj) [inline]

Definition at line 298 of file COWPtr.h.

References casa::False, and casa::True.

template<class T>
void casa::COWPtr< T >::setReadOnly ( ) [inline]

Definition at line 303 of file COWPtr.h.

References casa::True.


Member Data Documentation

template<class T>
Bool casa::COWPtr< T >::const_p [protected]

Definition at line 268 of file COWPtr.h.

Referenced by casa::COWPtr< T >::operator=().

template<class T>
CountedPtr<T> casa::COWPtr< T >::obj_p [protected]

Definition at line 267 of file COWPtr.h.

Referenced by casa::COWPtr< T >::operator=().


The documentation for this class was generated from the following file: