Provenance of a Frame::Binding state. More...

#include <Provenance.hpp>

Inheritance diagram for CXXR::Provenance:

Collaboration diagram for CXXR::Provenance:

Classes
class	CompTime
	For sorting Provenance objects by timestamp. More...

Public Types
typedef std::set< const Provenance *, Provenance::CompTime >	Set
	Set of `const Provenance*` sorted by timestamp.

Public Member Functions
	Provenance (const Symbol sym, const CommandChronicle chron)
	Constructor.
const Set &	children () const
	Children of this Provenance object.
const CommandChronicle *	chronicle () const
	CommandChronicle for this Provenance object.
const RObject *	command () const
	Top-level command giving rise to this binding.
const String *	getTime () const
	Formatted timestamp as a CXXR::String.
std::pair < CommandChronicle::ParentVector::const_iterator, CommandChronicle::ParentVector::const_iterator >	parents () const
	Parents of this Provenance object.
const Symbol *	symbol () const
	Symbol bound by this binding.
const RObject *	value () const
	Value of xenogenous binding.
bool	isXenogenous () const
	Is this binding xenogenous?
unsigned int	serialNumber () const
	Return serial number.
void	setXenogenous (const RObject *value)
	Declare binding to be xenogenous.
double	timestamp () const
	Timestamp of this binding.
void	detachReferents ()
	Null out all references from this node to other nodes.
void	visitReferents (const_visitor *) 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 Set *	ancestors (const Set &roots)
	Ancestors of a set of Provenance objects.
static Set *	descendants (const Set &roots)
	Descendants of a set of Provenance objects.
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.

Friends
class	boost::serialization::access

Additional Inherited Members
Protected Member Functions inherited from CXXR::GCNode
virtual	~GCNode ()
Protected Member Functions inherited from CXXR::HeterogeneousListBase::Link
virtual	~Link ()

Detailed Description

Provenance of a Frame::Binding state.

This class records the provenance of an R binding, or more accurately the provenance of the state of an R binding at a particular time, where the state of a Frame::Binding in particular includes its value. However, for brevity, in the documentation of this class we will use the expression "this binding" to refer to the Frame::Binding object, and the state of that Frame::Binding object, to which this Provenance object relates. (It should be understood that this Frame::Binding object may subsequently have changed its state, or ceased to exist altogether.)

In particular a Provenance object records the time this binding was established, and the top-level command that gave rise to it. It also maintains links to information about the provenance of the parents and children of the binding. The parents of a binding state b are the binding states which were read by the top-level command before creating the binding state b, and may therefore have influenced the state b; children are defined analogously.

Xenogenesis:: Normally the value (and more generally) the state of a binding created during the evaluation of a top-level command will depend solely on the values of bindings previously read during the evaluation of that top-level command, and possibly on other aspects of the internal state of the R interpreter when evaluation of the command started. If this is not the case, then the binding (state) is described as xenogenous, and this property is recorded in the Provenance object. Moreover, if a binding is xenogenous, the value of the binding is also recorded within the Provenance object.

Constructor & Destructor Documentation

Provenance::Provenance	(	const Symbol *	sym,
		const CommandChronicle *	chron
	)

Constructor.

Parameters:

sym	Pointer to the Symbol bound by this binding.
chron	Pointer to the CommandChronicle for the command whose evaluation gave rise to this binding.

Member Function Documentation

Provenance::Set * Provenance::ancestors ( const Set & roots )

static

Ancestors of a set of Provenance objects.

Parameters:

roots An arbitrary Provenance::Set.

Returns:: Pointer to a Provenance::Set which is the closure of roots under the 'parent' relationship. This return value is allocated from the free store, and the calling code is responsible for deleting it in due course.

const Set& CXXR::Provenance::children ( ) const

inline

Children of this Provenance object.

Returns:: The set of Provenance objects relating to the children of this binding.

const CommandChronicle* CXXR::Provenance::chronicle ( ) const

inline

CommandChronicle for this Provenance object.

Returns:: pointer to the CommandChronicle for the top-level command that gave rise to this binding.

const RObject* CXXR::Provenance::command ( ) const

inline

Top-level command giving rise to this binding.

Returns:: pointer to the top-level command which was being evaluated when this binding was established.

Provenance::Set * Provenance::descendants ( const Set & roots )

static

Descendants of a set of Provenance objects.

Parameters:

roots An arbitrary Provenance::Set.

Returns:: Pointer to a Provenance::Set which is the closure of roots under the 'child' relationship. This return value is allocated from the free store, and the calling code is responsible for deleting it in due course.

void Provenance::detachReferents ( )

virtual

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

const String * Provenance::getTime ( ) const

Formatted timestamp as a CXXR::String.

Returns:: pointer to a CXXR::String representing the timestamp. The formatting of this string is currently locale-dependent.

Deprecated:: This should instead use R's native date-time classes.

bool CXXR::Provenance::isXenogenous ( ) const

inline

Is this binding xenogenous?

Returns:: true iff this binding is xenogenous.

std::pair< CommandChronicle::ParentVector::const_iterator, CommandChronicle::ParentVector::const_iterator > Provenance::parents ( ) const

Parents of this Provenance object.

Returns:: Iterator range comprising all parents of this binding.

unsigned int CXXR::Provenance::serialNumber ( ) const

inline

Return serial number.

During each session, each Provenance object created is given a unique serial number. This serial number is not preserved across sessions.

Returns:: This Provenance object's serial number.

void Provenance::setXenogenous ( const RObject * value )

Declare binding to be xenogenous.

By default, a Provenance is assumed to be associated with a non-xenogenous binding. This assumption can be overridden by calling this function.

Parameters:

value The value of the xenogenous binding, which (as a result of this call) is recorded inside the Provenance object.

const Symbol* CXXR::Provenance::symbol ( ) const

inline

Symbol bound by this binding.

Returns:: pointer to this Symbol bound by this binding.

double Provenance::timestamp ( ) const

Timestamp of this binding.

Returns:: the timestamp associated with this binding, expressed as the number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC).

const RObject* CXXR::Provenance::value ( ) const

inline

Value of xenogenous binding.

Returns:: if this binding is xenogenous, the stored value of the binding. Otherwise returns a null pointer.

void Provenance::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::GCNode.

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

Provenance.hpp ($Id: Provenance.hpp 1403 2013-09-12 07:46:53Z arr $)
Provenance.cpp ($Id: Provenance.cpp 1351 2013-03-08 15:12:28Z arr $)

Classes

Public Types

Public Member Functions

Static Public Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation