Loading...
Searching...
No Matches
casacore::COWPtr< T > Class Template Reference
casa package (libcasa_casa) » Utilities_module

More...

`#include <COWPtr.h>`

## Classes

class | Deleter
| Helper class to make deletion of object optional. More...

## 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.
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

std::shared_ptr< T > | obj_p
Bool | const_p

## Detailed Description

template<class T>
class casacore::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;
};
casacore::String
String: the storage and methods of handling collections of characters.
Definition String.h:223
casacore::get
const T & get() const
Definition RecordField.h:143

#### 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));
}
casacore::Array
Definition Array.h:155
casacore::Array::set
void set(const T &value)
Set every element of the array to "value." Also could use the assignment operator which assigns an ar...
casacore::COWPtr::COWPtr
COWPtr()
The default constructor: used to create a null pointer which is delete-able by the destructor.
Definition COWPtr.h:276
casacore::True
const Bool True
Definition aipstype.h:41

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 <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..\.
};
casacore::COWPtr::rwRef
T & rwRef()
return a readable and writable reference to this instance.
Definition COWPtr.h:317
casacore::IPosition
Definition IPosition.h:117
casacore::Float
float Float
Definition aipstype.h:52

### 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 182 of file COWPtr.h.

## Constructor & Destructor Documentation

## COWPtr() [1/3]

template<class T>

casacore::COWPtr< T >::COWPtr | ( |  | ) |

inline

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.

does nothing

Definition at line 276 of file COWPtr.h.

References const_p, casacore::False, obj_p, and casacore::True.

Referenced by COWPtr(), COWPtr(), and operator=().

## COWPtr() [2/3]

template<class T>

casacore::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();

References COWPtr(), casacore::False, and casacore::True.

## COWPtr() [3/3]

template<class T>

casacore::COWPtr< T >::COWPtr | ( | const COWPtr< T > & | other | ) |

inline

copy ctor with reference semantics

does nothing

Definition at line 284 of file COWPtr.h.

References const_p, COWPtr(), and obj_p.

## Member Function Documentation

## isNull()

template<class T>

Bool casacore::COWPtr< T >::isNull | ( |  | ) | const

inline

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

Definition at line 323 of file COWPtr.h.

References obj_p.

## isReadOnly()

template<class T>

Bool casacore::COWPtr< T >::isReadOnly | ( |  | ) | const

inline

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

Definition at line 328 of file COWPtr.h.

References const_p.

## isUnique()

template<class T>

Bool casacore::COWPtr< T >::isUnique | ( |  | ) | const

inline

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

Definition at line 333 of file COWPtr.h.

References const_p, casacore::False, obj_p, and casacore::True.

## makeUnique()

template<class T>

Bool casacore::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.

## operator*()

template<class T>

const T & casacore::COWPtr< T >::operator* | ( |  | ) | const

inline

return a reference to a const object.

This prevents "write" operations.

Definition at line 307 of file COWPtr.h.

References obj_p.

## operator->()

template<class T>

const T * casacore::COWPtr< T >::operator-> | ( |  | ) | const

inline

return a pointer to a const object.

This prevents "write" operations.

Definition at line 302 of file COWPtr.h.

References obj_p.

## operator=()

template<class T>

COWPtr< T > & casacore::COWPtr< T >::operator= | ( | const COWPtr< T > & | other | ) |

inline

assignment operator with reference semantics

Definition at line 293 of file COWPtr.h.

References const_p, COWPtr(), and obj_p.

## ref()

template<class T>

const T & casacore::COWPtr< T >::ref | ( |  | ) | const

inline

return a const reference to the object.

Definition at line 312 of file COWPtr.h.

References obj_p.

## rwRef()

template<class T>

T & casacore::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 317 of file COWPtr.h.

References casacore::makeUnique(), and obj_p.

## set()

template<class T>

void casacore::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();

References casacore::False, and casacore::True.

## Member Data Documentation

## const_p

template<class T>

Bool casacore::COWPtr< T >::const_p

protected

Definition at line 270 of file COWPtr.h.

Referenced by COWPtr(), COWPtr(), isReadOnly(), isUnique(), and operator=().

## obj_p

template<class T>

std::shared_ptr<T> casacore::COWPtr< T >::obj_p

protected

Definition at line 269 of file COWPtr.h.

Referenced by COWPtr(), COWPtr(), isNull(), isUnique(), operator*(), operator->(), operator=(), ref(), and rwRef().

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

- casa/Utilities/COWPtr.h