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

#include <COWPtr.h>

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
COWPtr &	operator= (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

none

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:

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 COWPtr<Array> 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.
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.

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)

default constructor
assignment operator

Thrown Exceptions

AipsError

To Do

none

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]

return a const reference to the object.

Definition at line 318 of file COWPtr.h.

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.