Mechanism for deferred evaluation. More...

#include <Promise.h>

Inheritance diagram for CXXR::Promise:

Collaboration diagram for CXXR::Promise:

Public Member Functions
	Promise (RObject valgen, Environment env)
Environment *	environment () const
	Access the environment of the Promise.
RObject *	force ()
	Force the Promise.
bool	isMissingSymbol () const
	Not for general use.
void	setValue (RObject *val)
	Set value of the Promise.
RObject *	value ()
	Access the value of a Promise.
const RObject *	valueGenerator () const
	RObject to be evaluated by the Promise.
RObject *	evaluate (Environment *env)
	Evaluate object in a specified Environment.
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 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 *	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 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?
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 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 ()
Protected Member Functions inherited from CXXR::HeterogeneousListBase::Link
virtual	~Link ()

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

Mechanism for deferred evaluation.

This class is used to handle function arguments within R's lazy evaluation scheme. A Promise object encapsulates a pointer to an arbitrary RObject (typically a Symbol or an Expression), and a pointer to an Environment. When the Promise is first evaluated, the RObject is evaluated within the Environment, and the result of evaluation returned as the value of the Promise.

After the first evaluation, the result of evaluation is cached within the Promise object, and the Environment pointer is set null (thus possibly allowing the Environment to be garbage-collected). Subsequent evaluations of the Promise object simply return the cached value.

Note:: When a Promise is evaluated via a call to evaluate() (the virtual function defined in class RObject), the env parameter to evaluate() is ignored: evaluation uses only the Environment encapsulated within the Promise object. When an RObject is known to be a Promise, it is suggested that evaluation be carried out using the function Promise::force(), which lacks the redundant parameter and is consequently clearer to readers of the code.

Constructor & Destructor Documentation

CXXR::Promise::Promise	(	RObject *	valgen,
		Environment *	env
	)

inline

Parameters:

valgen	pointer to RObject to be evaluated to provide the value of the Promise. Can be null.
env	pointer to the Environment in which valgen is to be evaluated. If this pointer is null, the value of the Promise is immediately set to be valgen itself.

Member Function Documentation

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

Environment* CXXR::Promise::environment ( ) const

inline

Access the environment of the Promise.

Returns:: Pointer to the environment of the Promise. This will be a null pointer after the promise has been evaluated.

RObject* CXXR::Promise::evaluate ( Environment * env )

virtual

Evaluate object in a specified Environment.

Parameters:

env	Pointer to the environment in which evaluation is to take place.

Returns:: Pointer to the result of evaluation.

Reimplemented from CXXR::RObject.

RObject* CXXR::Promise::force ( )

inline

Force the Promise.

i.e. evaluate the value generator of the Promise within the Environment of the Promise. Following this, the environment pointer is set null, thus possibly allowing the Environment to be garbage-collected.

If this function is used on a Promise that has already been forced, it simply returns the previously computed value.

Returns:: The value of the Promise, i.e. the result of evaluating the value generator.

bool CXXR::Promise::isMissingSymbol ( ) const

Not for general use.

This function is used by isMissingArgument(). It implements some logic from CR's R_isMissing() which I don't fully understand.

Returns:: true iff ... well, read the code!

void CXXR::Promise::setValue ( RObject * val )

Set value of the Promise.

Once the value is set to something other than Symbol::unboundValue(), the environment pointer is set null.

Parameters:

val	Value to be associated with the Promise.

Todo:: Should be private (or removed entirely), but currently still used in saveload.cpp.

static const char* CXXR::Promise::staticTypeName ( )

inlinestatic

The name by which this type is known in R.

Returns:: The name by which this type is known in R.

const char* CXXR::Promise::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.

RObject* CXXR::Promise::value ( )

inline

Access the value of a Promise.

Returns:: pointer to the value of the Promise, or to Symbol::unboundValue() if it has not yet been evaluated.

const RObject* CXXR::Promise::valueGenerator ( ) const

inline

RObject to be evaluated by the Promise.

Returns:: const pointer to the RObject to be evaluated by the Promise.

void CXXR::Promise::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:

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

Promise.h ($Id: Promise.h 1353 2013-03-18 16:59:38Z arr $)

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation