SimTK::PIMPLImplementation< HANDLE, IMPL > Class Template Reference

This class provides some infrastructure useful in creating PIMPL Implementation classes (the ones referred to by Handles). More...

Public Member Functions
	PIMPLImplementation (HANDLE *h=0)
	This serves as a default constructor and as a way to construct an implementation class which already knows its owner handle. More...
int	getHandleCount () const
	Get the number of handles known to be referencing this implementation. More...
void	incrementHandleCount () const
	Register that a new handle is referencing this implementation so we won't delete the implementation prematurely. More...
int	decrementHandleCount () const
	Register the fact that one of the previously-referencing handles no longer references this implementation. More...
	~PIMPLImplementation ()
	Note that the base class destructor is non-virtual, although it is expected that derived classes will be abstract. More...
	PIMPLImplementation (const PIMPLImplementation &)
	The copy constructor for the base class makes sure that the new object has a null owner handle. More...
PIMPLImplementation &	operator= (const PIMPLImplementation &src)
	Copy assignment for the base class just makes sure that the owner handle is not copied, and that the handle count is zero for the copy. More...
void	setOwnerHandle (HANDLE &p)
	Provide an owner handle for an implementation which currently does not have one. More...
int	removeOwnerHandle ()
	Remove the owner reference from an implementation that currently has an owner. More...
void	replaceOwnerHandle (HANDLE &p)
	Replace the current owner handle with another one. More...
bool	hasOwnerHandle () const
	Check whether this implementation currently has a reference to its owner handle. More...
bool	isOwnerHandle (const HANDLE &p) const
	Check whether a given Handle of the appropriate type is the owner of this implementation. More...
const HANDLE &	getOwnerHandle () const
	Return a reference to the owner handle of this implementation. More...

Detailed Description

template<class HANDLE, class IMPL>
class SimTK::PIMPLImplementation< HANDLE, IMPL >

This class provides some infrastructure useful in creating PIMPL Implementation classes (the ones referred to by Handles).

Note that this class is used by SimTK Core code ONLY on the library side; it never appears in headers intended for use by clients. However it is generally useful enough that we include it here to assist people who would like to make their own PIMPL classes. Consequently, there are no binary compatibility issues raised by the exposure of data members here, and no guarantees that they won't change from release to relase of the SimTK Core; if the definition should change at some point the library code will change but it will be using the updated definition and does not have to coordinate in any way with client code.

Other users of this class should be aware that if you include it in code you expose to your own users you may create binary compatibility problems for yourself. Better to restrict use of this class (and indeed inclusion of this header file) to your private ".cpp" source code and not in your API header files.

The PIMPLImplementation base class keeps track of how many Handles are referencing it, so that that the last handle to be deleted can delete the implementation. One handle is designated as the "owner" handle of this implementation. We keep a pointer to that handle here, so special handling is required if the owner handle is deleted while other references still exist.

Constructor & Destructor Documentation

PIMPLImplementation() [1/2]

template<class HANDLE , class IMPL >

SimTK::PIMPLImplementation< HANDLE, IMPL >::PIMPLImplementation ( HANDLE *  h = 0 )

explicit

This serves as a default constructor and as a way to construct an implementation class which already knows its owner handle.

If the handle is supplied then the handle count is set to one. If not (default constructor) owner handle is null and the handle count at 0.

~PIMPLImplementation()

template<class HANDLE , class IMPL >

SimTK::PIMPLImplementation< HANDLE, IMPL >::~PIMPLImplementation

(

)

Note that the base class destructor is non-virtual, although it is expected that derived classes will be abstract.

Be sure to provide a virtual destructor in any abstract class which is derived from this base, and be sure to delete a pointer to the abstract class not a pointer to this base class!

PIMPLImplementation() [2/2]

template<class HANDLE , class IMPL >

SimTK::PIMPLImplementation< HANDLE, IMPL >::PIMPLImplementation

(

const PIMPLImplementation< HANDLE, IMPL > &

)

The copy constructor for the base class makes sure that the new object has a null owner handle.

A derived class must set the appropriate owner handle after this is called, that is, in the body (not the initializer list) of the derived class's copy constructor. Also the caller must make sure to increment the handle count.

Member Function Documentation

getHandleCount()

template<class HANDLE , class IMPL >

int SimTK::PIMPLImplementation< HANDLE, IMPL >::getHandleCount

(

)

const

Get the number of handles known to be referencing this implementation.

incrementHandleCount()

template<class HANDLE , class IMPL >

void SimTK::PIMPLImplementation< HANDLE, IMPL >::incrementHandleCount

(

)

const

Register that a new handle is referencing this implementation so we won't delete the implementation prematurely.

decrementHandleCount()

template<class HANDLE , class IMPL >

int SimTK::PIMPLImplementation< HANDLE, IMPL >::decrementHandleCount

(

)

const

Register the fact that one of the previously-referencing handles no longer references this implementation.

The remaining number of references is returned; if it is zero the caller should delete the implementation.

operator=()

template<class HANDLE , class IMPL >

PIMPLImplementation< HANDLE, IMPL > & SimTK::PIMPLImplementation< HANDLE, IMPL >::operator=

(

const PIMPLImplementation< HANDLE, IMPL > &

src

)

Copy assignment for the base class just makes sure that the owner handle is not copied, and that the handle count is zero for the copy.

Caller is required to register a handle and increment the handle counter.

setOwnerHandle()

template<class HANDLE , class IMPL >

void SimTK::PIMPLImplementation< HANDLE, IMPL >::setOwnerHandle

(

HANDLE &

p

)

Provide an owner handle for an implementation which currently does not have one.

This can't be used to replace the owner handle. This will increment the handle count also.

removeOwnerHandle()

template<class HANDLE , class IMPL >

int SimTK::PIMPLImplementation< HANDLE, IMPL >::removeOwnerHandle

(

)

Remove the owner reference from an implementation that currently has an owner.

This decrements the handle count also. The number of remaining handles is returned.

replaceOwnerHandle()

template<class HANDLE , class IMPL >

void SimTK::PIMPLImplementation< HANDLE, IMPL >::replaceOwnerHandle

(

HANDLE &

p

)

Replace the current owner handle with another one.

This can't be used to set the initial owner handle; just to replace an existing one with a new one. The handle count is not changed here.

hasOwnerHandle()

template<class HANDLE , class IMPL >

bool SimTK::PIMPLImplementation< HANDLE, IMPL >::hasOwnerHandle

(

)

const

Check whether this implementation currently has a reference to its owner handle.

isOwnerHandle()

template<class HANDLE , class IMPL >

bool SimTK::PIMPLImplementation< HANDLE, IMPL >::isOwnerHandle

(

const HANDLE &

p

)

const

Check whether a given Handle of the appropriate type is the owner of this implementation.

getOwnerHandle()

template<class HANDLE , class IMPL >

const HANDLE & SimTK::PIMPLImplementation< HANDLE, IMPL >::getOwnerHandle

(

)

const

Return a reference to the owner handle of this implementation.

This will throw an exception if there is no owner handle currently known to this implementation.

---

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

• PrivateImplementation.h
• PrivateImplementation_Defs.h