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

Weak reference. More...

#include <WeakRef.h>

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

List of all members.

Public Member Functions

 WeakRef (RObject *key, RObject *value, FunctionBase *R_finalizer=0, bool finalize_on_exit=false)
 WeakRef (RObject *key, RObject *value, R_CFinalizer_t C_finalizer, bool finalize_on_exit=false)
RObjectkey () const
RObjectvalue () const
unsigned int packGPBits () const
 Reproduce the gp bits field used in CR.
void unpackGPBits (unsigned int gpbits)
 Interpret the gp bits field used in CR.
- 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 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 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::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 bool check ()
 Integrity check.
static void runExitFinalizers ()
 Run finalizers with 'finalize_on_exit' specified.
static bool runFinalizers ()
 Run finalizers.
- 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.
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 GCNode
class SchwarzCounter< WeakRef >

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

Weak reference.

Refer to Stretching the storage manager: weak pointers and stable names in Haskell by Peyton Jones, Marlow, and Elliott (at www.research.microsoft.com/Users/simonpj/papers/weak.ps.gz) for the motivation and implementation of this class.

Each WeakRef has a key and, optionally, a value and/or a finalizer. The finalizer may either be a C function or an R object. The mark-sweep garbage collector will consider the value and finalizer to be reachable provided the key is reachable.

If, during a garbage collection, the key is found not to be reachable then the finalizer (if any) will be run, and the weak reference object will be 'tombstoned', so that subsequent calls to key() and value() will return null pointers.

A WeakRef object with a reachable key will not be garbage collected even if the WeakRef object is not itself reachable.

Note:
A WeakRef object takes steps to ensure that the reference counts of itself and its key, value and R finalizer (if they exist) never fall to zero until the WeakRef is tombstoned. Consequently these objects will only be garbage collected as part of a mark-sweep collection. In particular, it can be guaranteed that the finalizer of a WeakRef will be run as part of the same mark-sweep collection in which the key of that WeakRef is garbage-collected (having been found to be unreachable).
Todo:
It would probably make more sense for this class to inherit directly from GCNode, and for the key, value etc. to be pointers to GCNode.

Constructor & Destructor Documentation

CXXR::WeakRef::WeakRef ( RObject key,
RObject value,
FunctionBase R_finalizer = 0,
bool  finalize_on_exit = false 
)
Parameters:
keyPointer to the key of the WeakRef. It is not forbidden but probably pointless for the key to be null: in this event the reference will immediately be tombstoned, and its finalizer (if any) will never be run.
valuePointer to the value of the WeakRef (may be null)
R_finalizerPointer to an R object to be evaluated as a finalizer (may be null). The finalizer will be called with the key of the WeakRef object as its argument, and at the time of call the key and finalizer will be protected from the garbage collector. However, the WeakRef object itself will already have been tombstoned.
finalize_on_exitTrue iff the finalizer should be run when CXXR exits.
Note:
The constructors of WeakRef are unusual in that they themselves expose the constructed object to garbage collection. WeakRef objects must therefore be created using new WeakRef(...) rather than CXXR_NEW(WeakRef(...)).
CXXR::WeakRef::WeakRef ( RObject key,
RObject value,
R_CFinalizer_t  C_finalizer,
bool  finalize_on_exit = false 
)
Parameters:
keyPointer to the key of the WeakRef. It is not forbidden but probably pointless for the key to be null: in this event the reference will immediately be tombstoned, and its finalizer (if any) will never be run.
valuePointer to the value of the WeakRef (may be null). The finalizer will be called with a pointer to the key of the WeakRef object as its argument, and at the time of call the key object will be protected from the garbage collector. However, the WeakRef object itself will already have been tombstoned.
C_finalizerPointer to an C function to be invoked as a finalizer (may be null).
finalize_on_exitTrue iff the finalizer should be run when CXXR exits.
Note:
The constructors of WeakRef are unusual in that they themselves expose the constructed object to garbage collection. WeakRef objects must therefore be created using new WeakRef(...) rather than CXXR_NEW(WeakRef(...)).

Member Function Documentation

static bool CXXR::WeakRef::check ( )
static

Integrity check.

Aborts the program with an error message if the class is found to be internally inconsistent.

Returns:
true, if it returns at all. The return value is to facilitate use with assert.

Reimplemented from CXXR::GCNode.

void CXXR::WeakRef::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.

RObject* CXXR::WeakRef::key ( ) const
inline
Returns:
Pointer to the key of the WeakRef.
unsigned int CXXR::WeakRef::packGPBits ( ) const
virtual

Reproduce the gp bits field used in CR.

This function is used to reproduce the sxpinfo_struct.gp field used in CR. It should be used exclusively for serialization. Refer to the 'R Internals' document for details of this field.

Returns:
the reconstructed gp bits field (within the least significant 16 bits).
Note:
If this function is overridden in a derived class, the overriding function should call packGPBits() for its immediate base class, and then 'or' further bits into the result.

Reimplemented from CXXR::RObject.

static void CXXR::WeakRef::runExitFinalizers ( )
static

Run finalizers with 'finalize_on_exit' specified.

Run the finalizers of all (non-tombstoned) WeakRef object for which 'finalize_on_exit' was specified.

static bool CXXR::WeakRef::runFinalizers ( )
static

Run finalizers.

This is called by GCManager::gc() immediately after garbage collection, and runs the finalizers of any weak references that were identified during the garbage collection as being ready to finalize; when the call exits, all such weak references will have been tombstoned. (Consequently, calling this method at any other time will effectively be a no-op.)

Returns:
true iff any finalizers are actually run (whether successfully or not).
void CXXR::WeakRef::unpackGPBits ( unsigned int  gpbits)
virtual

Interpret the gp bits field used in CR.

This function is used to interpret the sxpinfo_struct.gp field used in CR in a way appropriate to a particular node class. It should be used exclusively for deserialization. Refer to the 'R Internals' document for details of this field.

Parameters:
gpbitsthe gp bits field (within the least significant 16 bits).
Note:
If this function is overridden in a derived class, the overriding function should also pass its argument to unpackGPBits() for its immediate base class.

Reimplemented from CXXR::RObject.

RObject* CXXR::WeakRef::value ( ) const
inline
Returns:
Pointer to the value of the WeakRef.

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