Provenance of a Frame::Binding state. More...
#include <Provenance.hpp>
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
| CXXR::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
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.
|
inline |
Children of this Provenance object.
- Returns:
- The set of Provenance objects relating to the children of this binding.
|
inline |
CommandChronicle for this Provenance object.
- Returns:
- pointer to the CommandChronicle for the top-level command that gave rise to this binding.
|
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.
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.
|
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.
|
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.
|
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:
-
value The value of the xenogenous binding, which (as a result of this call) is recorded inside the Provenance object.
|
inline |
| 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).
|
inline |
Value of xenogenous binding.
- Returns:
- if this binding is xenogenous, the stored value of the binding. Otherwise returns a null pointer.
|
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 file:
