|
| | COWPtr () |
| | The default constructor: used to create a null pointer which is delete-able by the destructor. More...
|
| |
| | 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. More...
|
| |
| | COWPtr (const COWPtr< T > &other) |
| | copy ctor with reference semantics More...
|
| |
| COWPtr & | operator= (const COWPtr< T > &other) |
| | assignment operator with reference semantics More...
|
| |
| const T * | operator-> () const |
| | return a pointer to a const object. More...
|
| |
| const T & | operator* () const |
| | return a reference to a const object. More...
|
| |
| void | set (T *obj, Bool deleteIt=True, Bool readOnly=False) |
| | Function used to change this instance of COWPtr. More...
|
| |
| void | setReadOnly (const T *obj) |
| |
| void | setReadOnly () |
| |
| const T & | ref () const |
| | return a const reference to the object. More...
|
| |
| T & | rwRef () |
| | return a readable and writable reference to this instance. More...
|
| |
| Bool | isNull () const |
| | returns False if this contains a non-null ptr, otherwise, return True. More...
|
| |
| Bool | isReadOnly () const |
| | returns True if the object is const, otherwise, return False. More...
|
| |
| Bool | isUnique () const |
| | returns True if the object is the only instance, otherwise, return False. More...
|
| |
| Bool | makeUnique () |
| | Return True if copied, otherwise, False. More...
|
| |
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
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:
String()
: itsRep (new StringRep;) {}
void set (
const char* str) {itsRep.rwRef().set (str);}
const char* get const {return itsRep.ref();}
private:
COWPtr<StringRep> itsRep;
};
class StringRep {
friend class String;
private:
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){
Array<Float> &nonConstArray = (Array<Float> &)staticConstArray;
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.)
main(){
COWPtr<Array<Float> > COW;
myFunc(COW);
Float someVal = COW->operator()(IPosition(2,3,3))
COW.rwRef().set(42.0f);
};
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
To Do
Definition at line 43 of file Lattice.h.
1.8.5