CXXR (C++ R) API
Public Member Functions | Static Public Member Functions | Protected Member Functions | Friends
CXXR::ExternalPointer Class Reference

External pointer. More...

#include <ExternalPointer.h>

Inheritance diagram for CXXR::ExternalPointer:
Inheritance graph
[legend]
Collaboration diagram for CXXR::ExternalPointer:
Collaboration graph
[legend]

List of all members.

Public Member Functions

 ExternalPointer (void *ptr=0, RObject *tag=0, RObject *prot=0)
const RObjectprotege () const
 Get const pointer to protege object.
RObjectprotege ()
 Get pointer to protege object.
const void * ptr () const
 Get the encapsulated pointer, qualified by const.
void * ptr ()
 Get the encapsulated pointer.
void setProtege (RObject *prot)
 Designate the protege object.
void setPtr (void *ptr)
 Set the value of the encapsulated pointer.
void setTag (RObject *tag)
 Set the 'tag' value.
const RObjecttag () const
 Get const pointer to tag object.
RObjecttag ()
 Get pointer to tag object.
const char * typeName () const
 Name within R of this type of object.
void visitReferents (const_visitor *v) const
 Conduct a visitor to the nodes referred to by this one.
- Public Member Functions inherited from CXXR::RObject
virtual const PairListattributes () const
 Get object attributes.
virtual void clearAttributes ()
 Remove all attributes.
virtual RObjectclone () const
 Return pointer to a copy of this object.
void copyAttribute (const Symbol *name, const RObject *source)
 Copy an attribute from one RObject to another.
void copyAttributes (const RObject *source, bool copyS4)
 Copy attributes from one RObject to another.
virtual RObjectevaluate (Environment *env)
 Evaluate object in a specified Environment.
virtual RObjectgetAttribute (const Symbol *name) const
 Get the value a particular attribute.
virtual bool hasAttributes () const
 Has this object any attributes?
bool hasClass () const
 Has this object the class attribute?
bool isS4Object () const
 Is this an S4 object?
void maybeTraceMemory (const RObject *src)
 Carry out memory tracing.
void maybeTraceMemory (const RObject *src1, const RObject *src2)
 Carry out memory tracing.
void maybeTraceMemory (const RObject *src1, const RObject *src2, const RObject *src3)
 Carry out memory tracing.
bool memoryTraced () const
 Is copying etc. of this object being traced?
virtual unsigned int packGPBits () const
 Reproduce the gp bits field used in CR.
virtual void setAttribute (const Symbol *name, RObject *value)
 Set or remove an attribute.
void setAttributes (const PairList *new_attributes)
 Replace the attributes of an object.
void setMemoryTracing (bool on)
 Enable/disable tracing of copying etc.
void setS4Object (bool on)
 Set the status of this RObject as an S4 object.
SEXPTYPE sexptype () const
 Get an object's SEXPTYPE.
virtual void unpackGPBits (unsigned int gpbits)
 Interpret the gp bits field used in CR.
- Public Member Functions inherited from CXXR::GCNode
void expose () const
 Record that construction of a node is complete.
bool isExposed () const
 Has this node been exposed to garbage collection?

Static Public Member Functions

static const char * staticTypeName ()
 The name by which this type is known in R.
- Static Public Member Functions inherited from CXXR::RObject
template<class T >
static T * clone (const T *pattern)
 Return a pointer to a copy of an object.
- Static Public Member Functions inherited from CXXR::GCNode
static void * operator new (size_t bytes)
 Allocate memory.
static void * operator new (size_t, void *where)
 Placement new for GCNode.
static void operator delete (void *p, size_t bytes)
 Deallocate memory.
static bool check ()
 Integrity check.
template<class T >
static T * expose (T *node)
 Record that construction of a node is complete.
static void gc ()
 Initiate a garbage collection.
static void gclite ()
 Lightweight garbage collection.
static void maybeCheckExposed (const GCNode *node)
 Subject to configuration, check that a GCNode is exposed.
static size_t numNodes ()
 Number of GCNode objects in existence.

Protected Member Functions

void detachReferents ()
 Null out all references from this node to other nodes.
- Protected Member Functions inherited from CXXR::RObject
 RObject (SEXPTYPE stype=CXXSXP)
 RObject (const RObject &pattern)
 Copy constructor.
- Protected Member Functions inherited from CXXR::GCNode
virtual ~GCNode ()

Friends

class boost::serialization::access

Additional Inherited Members

- Public Attributes inherited from CXXR::RObject
unsigned char m_named
unsigned m_missing: 2
unsigned m_argused: 2
bool m_active_binding: 1
bool m_binding_locked: 1

Detailed Description

External pointer.

RObject encapsulating a pointer to some entity that is not an RObject. An ExternalPointer also comprises two pointers to objects of a type derived from RObject, here designated the 'tag' and the 'protege', each of which is protected from garbage collection for the lifetime of the ExternalPointer object. The tag and the protege are treated identically by the ExternalPointer class, but the 'Writing R Extensions' document (in recent revisions) suggests that the tag be used for some sort of type identification, and that the protege be used for protecting memory (or other resources) used by the entity pointed to by the ExternalPointer.

Note:
Writers of C++ packages are recommended to derive their own classes from RObject rather than use this class, which is provided primarily to support the established C interface.

Constructor & Destructor Documentation

CXXR::ExternalPointer::ExternalPointer ( void *  ptr = 0,
RObject tag = 0,
RObject prot = 0 
)
inlineexplicit
Parameters:
ptrThe pointer that the ExternalPointer object is to encapsulate.
tagPointer to the tag object. May be null (and often is).
protPointer to the protege object. May be null (and often is).

Member Function Documentation

void CXXR::ExternalPointer::detachReferents ( )
protectedvirtual

Null out all references from this node to other nodes.

The referents of this node are those objects (derived from GCNode) designated by a GCEdge within this object. This function changes all GCEdges within this object to encapsulate a null pointer. It is used during the sweep phase of a mark-sweep garbage collection to break up unreachable subgraphs, and in particular to remove reference loops from them. After the application of this method, the GCNode should be regarded as a 'zombie', kept in existence only so other nodes can detach their references to it cleanly (using decRefCount()).

Note:
If this method is reimplemented in a derived class, the reimplemented version must remember to invoke detachReferents() for the immediate base class of the derived class, to ensure that all referents of the object get detached.

Reimplemented from CXXR::RObject.

const RObject* CXXR::ExternalPointer::protege ( ) const
inline

Get const pointer to protege object.

Returns:
a const pointer to the protege object of this ExternalPointer.
RObject* CXXR::ExternalPointer::protege ( )
inline

Get pointer to protege object.

Returns:
a pointer to the protege object of this ExternalPointer.
const void* CXXR::ExternalPointer::ptr ( ) const
inline

Get the encapsulated pointer, qualified by const.

Returns:
the encapsulated pointer, qualified by const.
void* CXXR::ExternalPointer::ptr ( )
inline

Get the encapsulated pointer.

Returns:
the encapsulated pointer.
void CXXR::ExternalPointer::setProtege ( RObject prot)
inline

Designate the protege object.

Parameters:
protPointer to the new protege object (or a null pointer).
void CXXR::ExternalPointer::setPtr ( void *  ptr)
inline

Set the value of the encapsulated pointer.

Parameters:
ptrNew pointer value (may be null).
void CXXR::ExternalPointer::setTag ( RObject tag)
inline

Set the 'tag' value.

Parameters:
tagPointer to the new tag object (or a null pointer).
static const char* CXXR::ExternalPointer::staticTypeName ( )
inlinestatic

The name by which this type is known in R.

Returns:
the name by which this type is known in R.
const RObject* CXXR::ExternalPointer::tag ( ) const
inline

Get const pointer to tag object.

Returns:
a const pointer to the 'tag' of this ExternalPointer.
RObject* CXXR::ExternalPointer::tag ( )
inline

Get pointer to tag object.

Returns:
a pointer to the 'tag' of this ExternalPointer.
const char* CXXR::ExternalPointer::typeName ( ) const
virtual

Name within R of this type of object.

Returns:
the name by which this type of object is known within R.

Reimplemented from CXXR::RObject.

void CXXR::ExternalPointer::visitReferents ( const_visitor v) const
virtual

Conduct a visitor to the nodes referred to by this one.

The referents of this node are those objects (derived from GCNode) designated by a GCEdge within this object.

Parameters:
vPointer to the visitor object.
Note:
If this method is reimplemented in a derived class, the reimplemented version must remember to invoke visitReferents() for the immediate base class of the derived class, to ensure that all referents of the object get visited. It is suggested that implementations set up stack-based pointers to all the referents of a node before visiting any of them; in that case, if the (recursive) visiting pushes the node out of the processor cache, there is no need to fetch it back in.

Reimplemented from CXXR::RObject.


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