CXXR (C++ R) API
Public Types | Public Member Functions
CXXR::GCStackRoot< T > Class Template Reference

Smart pointer to protect a GCNode from garbage collection. More...

#include <GCStackRoot.h>

Inheritance diagram for CXXR::GCStackRoot< T >:
Inheritance graph
[legend]
Collaboration diagram for CXXR::GCStackRoot< T >:
Collaboration graph
[legend]

List of all members.

Public Types

typedef T type

Public Member Functions

 GCStackRoot (T *node=0)
 GCStackRoot (const GCStackRoot &source)
 Copy constructor.
GCStackRootoperator= (const GCStackRoot &source)
GCStackRootoperator= (T *node)
T * operator-> () const
 Access member via encapsulated pointer.
T & operator* () const
 Dereference the encapsulated pointer.
 operator T * () const
 Implicit conversion to encapsulated pointer type.
T * get () const
 Access the encapsulated pointer.
 GCStackRoot (T *node=0)
 GCStackRoot (const GCStackRoot &source)
 Copy constructor.
GCStackRootoperator= (const GCStackRoot &source)
GCStackRootoperator= (T *node)
T * operator-> () const
 Access member via encapsulated pointer.
T & operator* () const
 Dereference the encapsulated pointer.
 operator T * () const
 Implicit conversion to encapsulated pointer type.
T * get () const
 Access the encapsulated pointer.

Additional Inherited Members

- Static Public Member Functions inherited from CXXR::GCStackRootBase
static void ppsRestoreSize (size_t new_size)
 Restore PPS to a previous size.
static size_t ppsSize ()
 Current size of PPS.
static unsigned int protect (RObject *node)
 Push a node pointer onto the PPS.
static void reprotect (RObject *node, unsigned int index)
 Change the target of a pointer on the PPS.
static void unprotect (unsigned int count=1)
 Pop pointers from the PPS.
static void unprotectPtr (RObject *node)
static void visitRoots (GCNode::const_visitor *v)
 Conduct a const visitor to all 'root' GCNode objects.
static void visitRoots (GCNode::const_visitor *v)
 Conduct a const visitor to protected objects.
- Protected Member Functions inherited from CXXR::GCStackRootBase
 GCStackRootBase (const GCNode *node)
 GCStackRootBase (const GCStackRootBase &source)
GCStackRootBaseoperator= (const GCStackRootBase &source)
void redirect (const GCNode *node)
 Change the node protected by this GCStackRootBase.
const GCNodeptr () const
 Access the encapsulated pointer.
 GCStackRootBase (const GCNode *node)
 Primary constructor.
 GCStackRootBase (const GCStackRootBase &source)
 Copy constructor.
GCStackRootBaseoperator= (const GCStackRootBase &source)
void retarget (const GCNode *node)
 Change the node protected by this GCStackRootBase.
const GCNodeptr () const
 Access the encapsulated pointer.

Detailed Description

template<class T = RObject>
class CXXR::GCStackRoot< T >

Smart pointer to protect a GCNode from garbage collection.

This class encapsulates a pointer to an object of a type derived from GCNode. For as long as the GCStackRoot object exists, the GCNode that it points to will not be garbage collected.

GCStackRoot objects are intended to be allocated on the processor stack: specifically, the class implementation requires that GCStackRoot objects are destroyed in the reverse order of creation, and the destructor checks this.

Parameters:
TGCNode or a type publicly derived from GCNode. This may be qualified by const, so for example a const String* may be encapsulated in a GCStackRoot using the type GCStackRoot<const String>.
Caller protects:
Suppose some code calls a function (or class method) that takes a pointer or reference to a class derived from GCNode as an argument, and/or returns a pointer to a class derived from GCNode as its return value. In CXXR, the preferred coding approach is that the calling code should take responsibility for protecting the arguments from the garbage collector before calling the function, and likewise take responsibility for protecting the returned value. This is because the calling code is in a better position to decide whether any additional steps are necessary to achieve this, and what they should be. (The calling code may also need to protect other objects: objects that are neither arguments to or values returned from the called function, but which would otherwise be vulnerable if the called function gave rise to a garbage collection.)

This class encapsulates a pointer to an object of a type derived from GCNode. For as long as the GCStackRoot object exists, the GCNode that it points to will not be garbage collected.

GCStackRoot objects are intended to be allocated on the processor stack: specifically, the class implementation requires that GCStackRoot objects are destroyed in the reverse order of creation, and the destructor checks this.

Template Parameters:
TGCNode or a type publicly derived from GCNode. This may be qualified by const, so for example a const String* may be encapsulated in a GCStackRoot using the type GCStackRoot<const String>.
Caller protects:
Suppose some code calls a function (or class method) that takes a pointer or reference to a class derived from GCNode as an argument, and/or returns a pointer to a class derived from GCNode as its return value. In CXXR, the preferred coding approach is that the calling code should take responsibility for protecting the arguments from the garbage collector before calling the function, and likewise take responsibility for protecting the returned value. This is because the calling code is in a better position to decide whether any additional steps are necessary to achieve this, and what they should be. (The calling code may also need to protect other objects: objects that are neither arguments to or values returned from the called function, but which would otherwise be vulnerable if the called function gave rise to a garbage collection.)

Constructor & Destructor Documentation

template<class T = RObject>
CXXR::GCStackRoot< T >::GCStackRoot ( T *  node = 0)
inlineexplicit
Parameters:
nodePointer the node to be pointed to, and protected from the garbage collector, or a null pointer.
template<class T = RObject>
CXXR::GCStackRoot< T >::GCStackRoot ( const GCStackRoot< T > &  source)
inline

Copy constructor.

The constructed GCStackRoot will protect the same GCNode as source. (There is probably no reason to use this constructor.)

template<class T = RObject>
CXXR::GCStackRoot< T >::GCStackRoot ( T *  node = 0)
inlineexplicit
Parameters:
nodePointer the node to be pointed to, and protected from the garbage collector, or a null pointer.
template<class T = RObject>
CXXR::GCStackRoot< T >::GCStackRoot ( const GCStackRoot< T > &  source)
inline

Copy constructor.

The constructed GCStackRoot will protect the same GCNode as source. (There is probably no reason to use this constructor.)


Member Function Documentation

template<class T = RObject>
T* CXXR::GCStackRoot< T >::get ( ) const
inline

Access the encapsulated pointer.

Returns:
the pointer currently encapsulated by the node.
template<class T = RObject>
T* CXXR::GCStackRoot< T >::get ( ) const
inline

Access the encapsulated pointer.

Returns:
the pointer currently encapsulated by the node.
template<class T = RObject>
CXXR::GCStackRoot< T >::operator T * ( ) const
inline

Implicit conversion to encapsulated pointer type.

Returns:
the pointer currently encapsulated by the node. The pointer is of type T* const to prevent its use as an lvalue, the effect of which would probably not be what the programmer wanted.
template<class T = RObject>
CXXR::GCStackRoot< T >::operator T * ( ) const
inline

Implicit conversion to encapsulated pointer type.

Returns:
the pointer currently encapsulated by the node. The pointer is of type T* const to prevent its use as an lvalue, the effect of which would probably not be what the programmer wanted.
template<class T = RObject>
T& CXXR::GCStackRoot< T >::operator* ( ) const
inline

Dereference the encapsulated pointer.

Returns:
a reference to the object pointed to by the encapsulated pointer. The effect is undefined if this object encapsulates a null pointer.
template<class T = RObject>
T& CXXR::GCStackRoot< T >::operator* ( ) const
inline

Dereference the encapsulated pointer.

Returns:
a reference to the object pointed to by the encapsulated pointer. The effect is undefined if this object encapsulates a null pointer.
template<class T = RObject>
T* CXXR::GCStackRoot< T >::operator-> ( ) const
inline

Access member via encapsulated pointer.

Returns:
the pointer currently encapsulated by the node.
template<class T = RObject>
T* CXXR::GCStackRoot< T >::operator-> ( ) const
inline

Access member via encapsulated pointer.

Returns:
the pointer currently encapsulated by the node.
template<class T = RObject>
GCStackRoot& CXXR::GCStackRoot< T >::operator= ( const GCStackRoot< T > &  source)
inline

This will cause this GCStackRoot to protect the same GCNode as is protected by source. (There is probably no reason to use this method.)

template<class T = RObject>
GCStackRoot& CXXR::GCStackRoot< T >::operator= ( T *  node)
inline

This will cause this GCStackRoot to point to and protect node, instead of the node (if any) it currently points to and protects.

Parameters:
nodePointer to the GCNode that is now to be pointed to and protected from the garbage collector.
template<class T = RObject>
GCStackRoot& CXXR::GCStackRoot< T >::operator= ( const GCStackRoot< T > &  source)
inline

This will cause this GCStackRoot to protect the same GCNode as is protected by source. (There is probably no reason to use this method.)

template<class T = RObject>
GCStackRoot& CXXR::GCStackRoot< T >::operator= ( T *  node)
inline

This will cause this GCStackRoot to point to and protect node, instead of the node (if any) it currently points to and protects.

Parameters:
nodePointer to the GCNode that is now to be pointed to and protected from the garbage collector.

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