This class provides some infrastructure useful in creating PIMPL Implementation classes (the ones referred to by Handles). More...
#include <PrivateImplementation.h>
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. | |
| int | getHandleCount () const |
| Get the number of handles known to be referencing this implementation. | |
| void | incrementHandleCount () const |
| Register that a new handle is referencing this implementation so we won't delete the implementation prematurely. | |
| int | decrementHandleCount () const |
| Register the fact that one of the previously-referencing handles no longer references this implementation. | |
| ~PIMPLImplementation () | |
| Note that the base class destructor is non-virtual, although it is expected that derived classes will be abstract. | |
| PIMPLImplementation (const PIMPLImplementation &) | |
| The copy constructor for the base class makes sure that the new object has a null owner handle. | |
| 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. | |
| void | setOwnerHandle (HANDLE &p) |
| Provide an owner handle for an implementation which currently does not have one. | |
| int | removeOwnerHandle () |
| Remove the owner reference from an implementation that currently has an owner. | |
| void | replaceOwnerHandle (HANDLE &p) |
| Replace the current owner handle with another one. | |
| bool | hasOwnerHandle () const |
| Check whether this implementation currently has a reference to its owner handle. | |
| bool | isOwnerHandle (const HANDLE &p) const |
| Check whether a given Handle of the appropriate type is the owner of this implementation. | |
| const HANDLE & | getOwnerHandle () const |
| Return a reference to the owner handle of this implementation. | |
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.
| PIMPLImplementation | ( | HANDLE * | h = 0 |
) | [inline, 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 | ( | ) | [inline] |
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 | ( | const PIMPLImplementation< HANDLE, IMPL > & | ) | [inline] |
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.
| int decrementHandleCount | ( | ) | const [inline] |
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.
Referenced by PIMPLImplementation< HANDLE, IMPL >::removeOwnerHandle().
| int getHandleCount | ( | ) | const [inline] |
Get the number of handles known to be referencing this implementation.
| const HANDLE & getOwnerHandle | ( | ) | const [inline] |
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.
References PIMPLImplementation< HANDLE, IMPL >::hasOwnerHandle().
| bool hasOwnerHandle | ( | ) | const [inline] |
Check whether this implementation currently has a reference to its owner handle.
Referenced by PIMPLImplementation< HANDLE, IMPL >::getOwnerHandle(), PIMPLImplementation< HANDLE, IMPL >::isOwnerHandle(), PIMPLImplementation< HANDLE, IMPL >::removeOwnerHandle(), PIMPLImplementation< HANDLE, IMPL >::replaceOwnerHandle(), and PIMPLImplementation< HANDLE, IMPL >::setOwnerHandle().
| void incrementHandleCount | ( | ) | const [inline] |
Register that a new handle is referencing this implementation so we won't delete the implementation prematurely.
Referenced by PIMPLImplementation< HANDLE, IMPL >::setOwnerHandle().
| bool isOwnerHandle | ( | const HANDLE & | p | ) | const [inline] |
Check whether a given Handle of the appropriate type is the owner of this implementation.
References PIMPLImplementation< HANDLE, IMPL >::hasOwnerHandle().
| PIMPLImplementation< HANDLE, IMPL > & operator= | ( | const PIMPLImplementation< HANDLE, IMPL > & | src | ) | [inline] |
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.
| int removeOwnerHandle | ( | ) | [inline] |
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.
References PIMPLImplementation< HANDLE, IMPL >::decrementHandleCount(), and PIMPLImplementation< HANDLE, IMPL >::hasOwnerHandle().
| void replaceOwnerHandle | ( | HANDLE & | p | ) | [inline] |
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.
References PIMPLImplementation< HANDLE, IMPL >::hasOwnerHandle().
| void setOwnerHandle | ( | HANDLE & | p | ) | [inline] |
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.
References PIMPLImplementation< HANDLE, IMPL >::hasOwnerHandle(), and PIMPLImplementation< HANDLE, IMPL >::incrementHandleCount().
1.6.1