Weak reference. More...

#include <WeakRef.h>

Inheritance diagram for CXXR::WeakRef:

Collaboration diagram for CXXR::WeakRef:

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)
RObject *	key () const
RObject *	value () 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 PairList *	attributes () const
	Get object attributes.
virtual void	clearAttributes ()
	Remove all attributes.
virtual RObject *	clone () 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 RObject *	evaluate (Environment *env)
	Evaluate object in a specified Environment.
virtual RObject *	getAttribute (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?
Public Member Functions inherited from CXXR::HeterogeneousListBase::Link
	Link ()
	Default constructor.
	Link (HeterogeneousListBase *list)
	Appending constructor.
void	freeLink ()
	Detach Link from any list.

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 ()
Protected Member Functions inherited from CXXR::HeterogeneousListBase::Link
virtual	~Link ()

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

WeakRef::WeakRef	(	RObject *	key,
		RObject *	value,
		FunctionBase *	R_finalizer = `0`,
		bool	finalize_on_exit = `false`
	)

Parameters:

key	Pointer 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.
value	Pointer to the value of the WeakRef (may be null)
R_finalizer	Pointer 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_exit	True 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(...)).

WeakRef::WeakRef	(	RObject *	key,
		RObject *	value,
		R_CFinalizer_t	C_finalizer,
		bool	finalize_on_exit = `false`
	)

Parameters:

key	Pointer 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.
value	Pointer 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_finalizer	Pointer to an C function to be invoked as a finalizer (may be null).
finalize_on_exit	True 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

bool 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 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 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.

void 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.

bool 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 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:

gpbits the 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 files:

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation