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

#include <GCStackRoot.h>

Inheritance diagram for CXXR::GCStackRoot< T >:

Collaboration diagram for CXXR::GCStackRoot< T >:

Public Types
typedef T	type

Public Member Functions
	GCStackRoot (T *node=0)
	GCStackRoot (const GCStackRoot &source)
	Copy constructor.
GCStackRoot &	operator= (const GCStackRoot &source)
GCStackRoot &	operator= (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.
GCStackRoot &	operator= (const GCStackRoot &source)
GCStackRoot &	operator= (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)
GCStackRootBase &	operator= (const GCStackRootBase &source)
void	redirect (const GCNode *node)
	Change the node protected by this GCStackRootBase.
const GCNode *	ptr () const
	Access the encapsulated pointer.
	GCStackRootBase (const GCNode *node)
	Primary constructor.
	GCStackRootBase (const GCStackRootBase &source)
	Copy constructor.
GCStackRootBase &	operator= (const GCStackRootBase &source)
void	retarget (const GCNode *node)
	Change the node protected by this GCStackRootBase.
const GCNode *	ptr () 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:

T	GCNode 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:

T	GCNode 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:

node	Pointer 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:

node	Pointer 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:

node	Pointer 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:

node	Pointer 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:

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

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

Constructor & Destructor Documentation

Member Function Documentation

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