CountedPtr.h

Classes

Global Functions -- act on dereference error (full description)
PtrRep -- Internal representation for CountedPtr (full description)
SimpleCountedConstPtr -- Simple referenced counted pointer for constant data (full description)
CountedConstPtr -- Regular referenced counted pointer for constant data (full description)
SimpleCountedPtr -- Simple referenced counted pointer to non-constant data (full description)
CountedPtr -- Regular referenced counted pointer for non-constant data (full description)

act on dereference error (source)

Interface

void throw_Null_CountedPtr_dereference_error()

Description

Synopsis

Global function that throws an exception. It is called by the member functions of the counted pointer classes when an un-initialized (null) pointer is followed.

Member Description

void throw_Null_CountedPtr_dereference_error()

template<class t> class PtrRep

Interface

Protected Members
PtrRep(t *v) : val(v), count(1), deletable(True)
PtrRep(t *v, Bool delit) : val(v), count(1), deletable(delit)
void freeVal()
~PtrRep()

Description

Review Status

Reviewed By:
Friso Olnon
Date Reviewed:
1995/03/15
Programs:
Tests:

Prerequisite

Synopsis

This class is a utility class for CountedConstPtr and CountedPtr. It stores the reference count and the pointer to the real data.

Tip It is currently a template and is used such that t is the true type of the stored pointer. This means, however, that when it is used, a template instantiation must be done for each type which t assumes. This makes debugging easier, but in the future all of these pointers could be declared with void type to avoid template instantiations.

Motivation

This class isolates all of the low level management of the reference.

Member Description

PtrRep(t *v) : val(v), count(1), deletable(True)
PtrRep(t *v, Bool delit) : val(v), count(1), deletable(delit)

This constructor sets up the reference count to one and initializes the pointer to the real data. The delit flag can be passed in to indicate whether the real data should be freed or not when the reference count reaches zero.

void freeVal()

This deletes the real data if indeed it can be deleted.

~PtrRep()

This destructor uses the deletable flag to indicate if the real data should be freed or not.

template<class t> class SimpleCountedConstPtr

Interface

Public Members
SimpleCountedConstPtr() : ref(0)
SimpleCountedConstPtr(t *val, Bool delit = True)
SimpleCountedConstPtr(const t *val)
SimpleCountedConstPtr(const SimpleCountedConstPtr<t> &val) : ref(val.ref)
virtual ~SimpleCountedConstPtr()
const t &operator*() const
Bool operator==(const SimpleCountedConstPtr<t> &other) const
Bool operator!=(const SimpleCountedConstPtr<t> &other) const
SimpleCountedConstPtr<t> &operator=(const SimpleCountedConstPtr<t> &val)
SimpleCountedConstPtr<t> &operator=(t *v)
uInt nrefs() const
void replace(t *v, Bool delit = True)
Bool null() const

Description

Review Status

Reviewed By:
Friso Olnon
Date Reviewed:
1995/03/15
Programs:
Tests:
  • tCountedPtr

Etymology

This class is Simple because it does not have the operator->() operator. This means that it puts less demands on the underlying type. It is Counted because it is reference counted, and it is Const because the underlying value is non-modifiable.

Synopsis

This class implements a simple reference counting mechanism. It allows SimpleCountedConstPtrs to be passed around freely, incrementing or decrementing the reference count as needed when one SimpleCountedConstPtr is assigned to another. When the reference count reaches zero the internal storage is deleted by default, but this behavior can be overridden.

This class is used as a pointer to constant data. As such, it only has the subset of the CountedConstPtr functions which are relevant for constant data.

Motivation

Reference counting

Member Description

SimpleCountedConstPtr() : ref(0)

This constructor allows for the creation of a null SimpleCountedConstPtr. The assignment operator can be used to assign a null SimpleCountedConstPtr from another pointer.

SimpleCountedConstPtr(t *val, Bool delit = True)

This constructor sets up a reference count for the val pointer. By default, the data pointed to by val will be deleted when it is no longer referenced. Passing in False for delit will prevent the data from being deleted when the reference count reaches zero.

Warning After the counted pointer is initialized the value should no longer be manipulated by the raw pointer of type t*.

SimpleCountedConstPtr(const t *val)

This constructor sets up a reference count for the val pointer. Since val is a pointer to constant data, the data will not be deleted when the reference count reaches zero.

Tip Since the constant data will NOT be cleaned up when the reference count reaches zero, the use of this class for pointers to constant data may not be desirable.

SimpleCountedConstPtr(const SimpleCountedConstPtr<t> &val) : ref(val.ref)

This copy constructor allows SimpleCountedConstPtrs to be initialized from other SimpleCountedConstPtrs.

virtual ~SimpleCountedConstPtr()

This destructor only deletes the really stored data when it was initialized as deletable and the reference count is zero.

const t &operator*() const

The SimpleCountedConstPtr indirection operator simply returns a reference to the value being protected. If the pointer is un-initialized (null), an exception will be thrown. The member function null() can be used to catch such a condition in time.

Thrown Exceptions

Tip The address of the reference returned should not be stored for later use.

Bool operator==(const SimpleCountedConstPtr<t> &other) const

Equality operator which checks to see if two SimpleCountedConstPtrs are pointing at the same thing.

Bool operator!=(const SimpleCountedConstPtr<t> &other) const

Non-equality operator which checks to see if two SimpleCountedConstPtrs are not pointing at the same thing.

SimpleCountedConstPtr<t> &operator=(const SimpleCountedConstPtr<t> &val)

This assignment operator allows SimpleCountedConstPtrs to be freely assigned to each other.

SimpleCountedConstPtr<t> &operator=(t *v)

This assignment operator allows the object to which the current SimpleCountedConstPtr points to be changed.

uInt nrefs() const

Sometimes it is useful to know if there is more than one reference made. This is a way of getting that. Of course the point of these classes is that this information is normally not required.

void replace(t *v, Bool delit = True)

This function changes the value for this SimpleCountedConstPtr and all of the other SimpleCountedConstPtrs which point to this same value.

Warning This is dangerous, and generally should not be done.

Bool null() const

Check to see if this SimpleCountedConstPtr is un-initialized, null.

template<class t> class CountedConstPtr : virtual public SimpleCountedConstPtr<t>

Interface

CountedConstPtr() : SimpleCountedConstPtr<t>()
CountedConstPtr(t *val, Bool delit = True) : SimpleCountedConstPtr<t>(val,delit)
CountedConstPtr(const CountedConstPtr<t> &val) : SimpleCountedConstPtr<t>(val)
CountedConstPtr<t> &operator=(const CountedConstPtr<t> &val)
CountedConstPtr<t> &operator=(t *v)
const t *operator->() const

Description

Review Status

Reviewed By:
Friso Olnon
Date Reviewed:
1995/03/15
Programs:
Tests:
  • tCountedPtr

Prerequisite

Synopsis

This class has the same objective as SimpleCountedConstPtr but it adds the operator->(). It still only contains a pointer whose underlying data cannot be changed. The destructor deletes the underlying data when the reference count reaches zero.

Motivation

operator->() is useful, but not always available for every type.

Member Description

CountedConstPtr() : SimpleCountedConstPtr<t>()

This constructor allows for the creation of a null CountedConstPtr. The assignment operator can be used to assign a null CountedConstPtr from another pointer.

CountedConstPtr(t *val, Bool delit = True) : SimpleCountedConstPtr<t>(val,delit)

This constructor sets up a reference count for the val pointer. By default, the data pointed to by val will be deleted when it is no longer referenced. Passing in False for delit will prevent the data from being deleted when the reference count reaches zero.

Warning After the counted pointer is initialized the value should no longer be manipulated by the raw pointer of type t*.

CountedConstPtr(const CountedConstPtr<t> &val) : SimpleCountedConstPtr<t>(val)

This copy constructor allows CountedConstPtrs to be initialized from other CountedConstPtrs.

CountedConstPtr<t> &operator=(const CountedConstPtr<t> &val)

This assignment operator allows CountedConstPtrs to be freely assigned to each other.

CountedConstPtr<t> &operator=(t *v)

This assignment operator allows the object to which the current CountedConstPtr points to be changed.

const t *operator->() const

This dereferencing operator behaves as expected; it returns the pointer to the value being protected, and then its dereferencing operator will be invoked as appropriate. If the pointer is un-initialized (null), an exception will be thrown. The member function null() can be used to catch such a condition in time.

Thrown Exceptions

template<class t> class SimpleCountedPtr : virtual public SimpleCountedConstPtr<t>

Interface

SimpleCountedPtr() : SimpleCountedConstPtr<t>()
SimpleCountedPtr(t *val, Bool delit = True) : SimpleCountedConstPtr<t>(val,delit)
SimpleCountedPtr(const SimpleCountedPtr<t> &val) : SimpleCountedConstPtr<t>(val)
SimpleCountedPtr<t> &operator=(const SimpleCountedPtr<t> &val)
SimpleCountedPtr<t> &operator=(t *v)
const t &operator*() const
t &operator*()

Description

Review Status

Reviewed By:
Friso Olnon
Date Reviewed:
1995/03/15
Programs:
Tests:
  • tCountedPtr

Prerequisite

Synopsis

This class, like SimpleCountedConstPtr, does not define the operator->(). Thus it can point to simple data which does not have this operator defined. In contrast to SimpleCountedConstPtr, this class points at non-constant underlying data. The deletion properties are the same for both classes.

Member Description

SimpleCountedPtr() : SimpleCountedConstPtr<t>()

This constructor allows for the creation of a null SimpleCountedPtr. The assignment operator can be used to assign a null SimpleCountedPtr from another pointer.

SimpleCountedPtr(t *val, Bool delit = True) : SimpleCountedConstPtr<t>(val,delit)

This constructor sets up a reference count for the val pointer. By default, the data pointed to by val will be deleted when it is no longer referenced. Passing in False for delit will prevent the data from being deleted when the reference count reaches zero.

Warning After the counted pointer is initialized the value should no longer be manipulated by the raw pointer of type t*.

SimpleCountedPtr(const SimpleCountedPtr<t> &val) : SimpleCountedConstPtr<t>(val)

This copy constructor allows SimpleCountedPtrs to be initialized from other SimpleCountedPtrs.

SimpleCountedPtr<t> &operator=(const SimpleCountedPtr<t> &val)

This assignment operator allows SimpleCountedPtrs to be freely assigned to each other.

SimpleCountedPtr<t> &operator=(t *v)

This assignment operator allows the object to which the current SimpleCountedPtr points to be changed.

const t &operator*() const
t &operator*()

The SimpleCountedPtr indirection operator simply returns a reference to the value being protected. If the pointer is un-initialized (null), an exception will be thrown. The member function null() can be used to catch such a condition in time.

Thrown Exceptions

Tip The address of the reference returned should not be stored for later use.

template<class t> class CountedPtr : public SimpleCountedPtr<t>, public CountedConstPtr<t>

Interface

CountedPtr()
CountedPtr(t *val, Bool delit = True)
CountedPtr(const CountedPtr<t> &val)
CountedPtr<t> &operator=(const CountedPtr<t> &val)
CountedPtr<t> &operator=(t *v)
t *operator->() const
t *operator->()

Description

Review Status

Reviewed By:
Friso Olnon
Date Reviewed:
1995/03/15
Programs:
Tests:
  • tCountedPtr

Prerequisite

Synopsis

This class completes the lattice. It inherits much of the members which deal with non-constant data from SimpleCountedPtr, and it inherits the const operator->() from CountedConstPtr. What this class adds is the operator->() which returns a modifiable pointer.

Member Description

CountedPtr()

This constructor allows for the creation of a null CountedPtr. The assignment operator can be used to assign a null CountedPtr from another pointer.

CountedPtr(t *val, Bool delit = True)

This constructor sets up a reference count for the val pointer. By default, the data pointed to by val will be deleted when it is no longer referenced. Passing in False for delit will prevent the data from being deleted when the reference count reaches zero.

Warning After the counted pointer is initialized the value should no longer be manipulated by the raw pointer of type t*.

CountedPtr(const CountedPtr<t> &val)

This copy constructor allows CountedPtrs to be initialized from other CountedPtrs.

CountedPtr<t> &operator=(const CountedPtr<t> &val)

This assignment operator allows CountedPtrs to be freely assigned to each other.

CountedPtr<t> &operator=(t *v)

This assignment operator allows the object to which the current CountedPtr points to be changed.

t *operator->() const
t *operator->()

This dereferencing operator behaves as expected; it returns the pointer to the value being protected, and then its dereferencing operator will be invoked as appropriate. If the pointer is un-initialized (null), an exception will be thrown. The member function null() can be used to catch such a condition in time.

Thrown Exceptions