CXXR (C++ R) API
Classes | Public Types | Public Member Functions | Static Public Member Functions | Friends
CXXR::Provenance Class Reference

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

#include <Provenance.hpp>

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

List of all members.

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 Setchildren () const
 Children of this Provenance object.
const CommandChroniclechronicle () const
 CommandChronicle for this Provenance object.
const RObjectcommand () const
 Top-level command giving rise to this binding.
const StringgetTime () 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 Symbolsymbol () const
 Symbol bound by this binding.
const RObjectvalue () 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?

Static Public Member Functions

static Setancestors (const Set &roots)
 Ancestors of a set of Provenance objects.
static Setdescendants (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 ()

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

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

Constructor.

Parameters:
symPointer to the Symbol bound by this binding.
chronPointer to the CommandChronicle for the command whose evaluation gave rise to this binding.

Member Function Documentation

static Set* CXXR::Provenance::ancestors ( const Set roots)
static

Ancestors of a set of Provenance objects.

Parameters:
rootsAn 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.
static Set* CXXR::Provenance::descendants ( const Set roots)
static

Descendants of a set of Provenance objects.

Parameters:
rootsAn 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 CXXR::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* CXXR::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> CXXR::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 CXXR::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:
valueThe 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 CXXR::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 CXXR::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:
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::GCNode.


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