Handle Class Template Reference

#include <ql/handle.hpp>

List of all members.


Detailed Description

template<class T>
class QuantLib::Handle< T >

Reference-counted pointer.

This class acts as a proxy to a pointer contained in it. Such pointer is owned by the handle, i.e., the handle will be responsible for its deletion, unless explicitly stated by the programmer.

A count of the references to the contained pointer is incremented every time a handle is copied, and decremented every time a handle is deleted or goes out of scope. When the handle owns the pointer, this mechanism ensures on one hand, that the pointer will not be deallocated as long as a handle refers to it, and on the other hand, that it will be deallocated when no more handles do.

Note:
The implementation of this class was originally taken from "The C++ Programming Language", 3rd ed., B.Stroustrup, Addison-Wesley, 1997.
Warning:
This mechanism will break and result in untimely deallocation of the pointer (and very possible death of your executable) if two handles are explicitly initialized with the same pointer, as in
SomeObj* so = new SomeObj; Handle<SomeObj> h1(so); Handle<SomeObj> h2 = h1; // this is safe. Handle<SomeObj> h3(so); // this is definitely not.
It is good practice to create the pointer and immediately pass it to the handle, as in
Handle<SomeObj> h1(new SomeObj); // this is as safe as can be.

When the programmer keeps the ownership of the pointer, as explicitly declared in

SomeObj so; Handle<SomeObj> h(&so,false);
it is responsibility of the programmer to make sure that the object remain in scope as long as there are handles pointing to it. Also, the programmer must explicitly delete the object if required.


Public Member Functions

constructors, destructor, and assignment
 Handle (T *ptr=0, bool owns=true)
 Constructor taking a pointer.

template<class U>  Handle (const Handle< U > &from)
 Handle (const Handle &from)
template<class U> Handleoperator= (const Handle< U > &from)
Handleoperator= (const Handle &from)
Dereferencing
T & operator * () const
T * operator-> () const
Inspectors
bool isNull () const
 Checks if the contained pointer is actually allocated.

bool operator== (const Handle< T > &) const
 Checks if the two handles point to the same object.

bool operator!= (const Handle< T > &) const

Friends

class HandleCopier


Constructor & Destructor Documentation

Handle T *  ptr = 0,
bool  owns = true
[explicit]
 

Constructor taking a pointer.

If owns is set to true (the default), the handle will be responsible for the deletion of the pointer. If it is set to false, the programmer must make sure that the pointed object remains in scope for the lifetime of the handle and its copies. Destruction of the object is also responsibility of the programmer.

It is advised that handles be used with owns = false only in a controlled an self-contained environment. Such a case happens when an object needs to pass a handle to itself to inner classes or bootstrappers - i.e., contained or temporary objects whose lifetime is guaranteed not to last more than the lifetime of the object.


QuantLib.org
QuantLib
Hosted by
SourceForge.net Logo
Documentation generated by
doxygen