PtrHolder.h

Classes

PtrHolder -- Hold and delete pointers not deleted by object destructors (full description)
SPtrHolder -- Hold and delete pointers not deleted by object destructors (full description)

template<class T> class PtrHolder

Interface

Public Members
PtrHolder()
PtrHolder(T *pointer, Bool isCArray = False)
~PtrHolder()
void set(T *pointer, Bool isCarray = False, Bool deleteCurrentPtr = True)
void clear(Bool deleteCurrentPtr = True)
T *ptr()
const T *ptr() const
Bool isCArray() const
Private Members
PtrHolder(const PtrHolder<T> &other)
PtrHolder<T> &operator=(const PtrHolder<T> &other)
void delete_pointer_if_necessary()

Description

Review Status

Reviewed By:
troberts
Date Reviewed:
1995/07/29
Programs:
Tests:

Prerequisite

Synopsis

PtrHolders hold allocated pointers which should be deleted when an exception is thrown. Exceptions only call destructors of objects. Thus, for example, storage allocated in a global function (outside of an object)is not deleted. A PtrHolder solves this problem: it merely holds the pointer and deletes it when it is destroyed itself, e.g. when an exception is thrown or when the function exits normally.

Example

    void func(Int *ptr); // some other function that takes a pointer
    // ...
    // True below means it's an array, False (the default) would mean
    // a singleton object.
    PtrHolder<Int> iholder(new Int[10000], True);
    func(iholder);                           // converts automatically to ptr
    (iholder.ptr() + 5) = 11;                // use pointer explicitly
    some_function_that_throws_exception();   // pointer is deleted

Motivation

Avoid leaks when throwing/catching exceptions.

To Do

Member Description

PtrHolder()

The default constructor uses a null pointer.

PtrHolder(T *pointer, Bool isCArray = False)

Construct a PtrHolder from a pointer which MUST have been allocated from new, since the destructor will call delete on it. If the pointer is to an array, i.e. allocated with operator new[], then isCarray should be set to True. (This parameter is required because C-arrays need to be deleted with delete[].)

After the pointer is placed into the holder, the user should not manually delete the pointer; the PtrHolder object will do that, unless set() or clear() is called with deleteCurrentPtr set to False. The pointer must also only be put into one holder to avoid double deletion.

~PtrHolder()

void set(T *pointer, Bool isCarray = False, Bool deleteCurrentPtr = True)

Set the pointer to a new value. If deleteCurrentPtr is True (the default), then delete the existing pointer first. If isCarray is True, then the new pointer is assumed to have been allocated with new[].

void clear(Bool deleteCurrentPtr = True)

Set the current pointer to null; if deletePtr is True (the default), then the current pointer is deleted first.

T *ptr()
const T *ptr() const

Attempt to automatically release a pointer when required. If the compiler can't figure it out, you can use the ptr() member function directly.

Bool isCArray() const

See if the pointer points to a C-array.

PtrHolder(const PtrHolder<T> &other)

PtrHolder<T> &operator=(const PtrHolder<T> &other)

void delete_pointer_if_necessary()

template<class T> class SPtrHolder

Interface

Public Members
explicit SPtrHolder (T* ptr = 0) : itsPtr(ptr)
~SPtrHolder()
void reset (T* ptr)
T* transfer()
void release()
T& operator*()
const T& operator*() const
T* operator->()
const T* operator->() const
T* ptr()
const T* ptr() const
Private Members
SPtrHolder(const SPtrHolder<T> &other)
SPtrHolder<T> &operator=(const SPtrHolder<T> &other)

Description

Review Status

Programs:
Tests:
  • tPtrHolder

Prerequisite

Synopsis

SPtrHolders hold allocated pointers to non-array objects which should be deleted when an exception is thrown. SPtrHolder is similar to PtrHolder, but easier to use and only valid for pointer to a single object, thus not to a C-array of objects.

Example

    void func(Table *ptr); // some other function that takes a pointer
    // ...
    // True below means it's an array, False (the default) would mean
    // a singleton object.
    SPtrHolder<Int> iholder(new Table(...));
    func(iholder);                           // converts automatically to ptr
    Table* tab = iholder.transfer();         // transfer ownership
If an exception is thrown in function func, the Table will be deleted automatically. After the function call, the ownership is tranfered back to the 'user'

Motivation

std::autoptr is harder to use and its future is unclear.
PtrHolder is not fully inlined and has C-array overhead. Furthermore the automatic conversion to a T* is dangerous, because the programmer may not be aware that the pointer is maybe taken over.

Member Description

explicit SPtrHolder (T* ptr = 0) : itsPtr(ptr)

Construct an SPtrHolder from a pointer which MUST have been allocated from new, since the destructor will After the pointer is placed into the holder, the user should not manually delete the pointer unless the transfer function is called. The pointer must also only be put into one holder to avoid double deletion.

~SPtrHolder()

void reset (T* ptr)

Reset the pointer.

T* transfer()

Transfer ownership of the pointer. I.e. return the pointer and set it to 0 in the object.

void release()

Release the pointer.

T& operator*()
const T& operator*() const

Make it possible to dereference the pointer object.

T* operator->()
const T* operator->() const

Make it possible to use -> on the pointer object.

T* ptr()
const T* ptr() const

Get the pointer for use.

SPtrHolder(const SPtrHolder<T> &other)
SPtrHolder<T> &operator=(const SPtrHolder<T> &other)

SPrtHolder cannot be copied.