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

Mapping from Symbols to R objects. More...

#include <Frame.hpp>

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

List of all members.

Classes

class  Binding
 Representation of a binding of a Symbol to an RObject. More...

Public Types

typedef boost::any_range
< const Binding,
boost::forward_traversal_tag,
const Binding
&, std::ptrdiff_t > 
BindingRange
 Allow iteration over a Frame object's Bindings.
typedef void(* monitor )(const Binding &)
 Function type for read and write monitors.

Public Member Functions

 Frame (const Frame &source)
 Copy constructor.
PairListasPairList () const
 Get contents as a PairList.
Bindingbind (const Symbol *symbol, RObject *value, Frame::Binding::Origin origin=Frame::Binding::EXPLICIT)
 Bind a Symbol to a specified value.
virtual Bindingbinding (const Symbol *symbol)=0
 Access binding of an already-defined Symbol.
virtual const Bindingbinding (const Symbol *symbol) const =0
 Access const binding of an already-defined Symbol.
virtual BindingRange bindingRange () const =0
 Obtain a BindingRange for this Frame.
void clear ()
 Remove all symbols from the Frame.
virtual Frameclone () const =0
 Return pointer to a copy of this Frame.
void enableReadMonitoring (bool on) const
 Enable monitored reading of Symbol values.
void enableWriteMonitoring (bool on) const
 Enable monitored writing of Symbol values.
bool erase (const Symbol *symbol)
 Remove the Binding (if any) of a Symbol.
bool isLocked () const
 Is the Frame locked?
void lock (bool lock_bindings)
 Lock this Frame.
virtual void lockBindings ()=0
 Lock all Bindings in this Frame.
BindingobtainBinding (const Symbol *symbol)
 Get or create a Binding for a Symbol.
virtual std::size_t size () const =0
 Number of Bindings in Frame.
std::vector< const Symbol * > symbols (bool include_dotsymbols) const
 Symbols bound by this Frame.
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?

Static Public Member Functions

static monitor setReadMonitor (monitor new_monitor)
 Define function to monitor reading of Symbol values.
static monitor setWriteMonitor (monitor new_monitor)
 Define function to monitor writing of Symbol values.
- 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 statusChanged (const Symbol *sym)
 Report change in the bound/unbound status of Symbol objects.
void detachReferents ()
 Null out all references from this node to other nodes.
- Protected Member Functions inherited from CXXR::GCNode
virtual ~GCNode ()

Friends

class Environment
class boost::serialization::access
class Binding

Detailed Description

Mapping from Symbols to R objects.

A Frame defines a mapping from (pointers to) CXXR::Symbol objects to (pointers to) arbitrary objects of classes derived from RObject. A Frame is usually, but not necessarily, associated with an Frame object. Frame itself is an abstract class; for most purposes its embodiment StdFrame should be used.


Member Typedef Documentation

typedef boost::any_range<const Binding, boost::forward_traversal_tag, const Binding&, std::ptrdiff_t> CXXR::Frame::BindingRange

Allow iteration over a Frame object's Bindings.

This is a boost::any_range type which allows for (read-only) iteration over the Binding objects within a Frame, irrespective of the underlying implementation of the Frame.

typedef void(* CXXR::Frame::monitor)(const Binding &)

Function type for read and write monitors.

See the documentation for setReadMonitor() and setWriteMonitor().


Constructor & Destructor Documentation

CXXR::Frame::Frame ( const Frame source)
inline

Copy constructor.

The copy will define the same mapping from Symbols to R objects as source; neither the R objects, nor of course the Symbols, are copied as part of the cloning.

The copy will be locked if source is locked. However, the copy will not have a read or write monitor.


Member Function Documentation

PairList* CXXR::Frame::asPairList ( ) const

Get contents as a PairList.

Access the contents of this Frame expressed as a PairList, with the tag of each PairList element representing a Symbol and the car value representing the object to which that Symbol is mapped, and with the Binding's active, locked and missing status indicated as in CR's FRAME() function.

Returns:
pointer to a PairList as described above.
Note:
The PairList is generated on demand, so this operation is relatively expensive in time. Modifications to the returned PairList will have no effect on the Frame itself.
Binding* CXXR::Frame::bind ( const Symbol symbol,
RObject value,
Frame::Binding::Origin  origin = Frame::Binding::EXPLICIT 
)
inline

Bind a Symbol to a specified value.

Parameters:
symbolNon-null pointer to the Symbol to be bound or rebound.
valuePointer, possibly null, to the RObject to which symbol is now to be bound. Any previous binding of symbol is overwritten.
originOrigin of the newly bound value.
Returns:
Pointer to the resulting Binding.
virtual Binding* CXXR::Frame::binding ( const Symbol symbol)
pure virtual

Access binding of an already-defined Symbol.

This function provides a pointer to the Binding of a Symbol. In this variant the pointer is non-const, and consequently the calling code can use it to modify the Binding (provided the Binding is not locked).

Parameters:
symbolThe Symbol for which a mapping is sought.
Returns:
A pointer to the required binding, or a null pointer if it was not found.

Implemented in CXXR::StdFrame.

virtual const Binding* CXXR::Frame::binding ( const Symbol symbol) const
pure virtual

Access const binding of an already-defined Symbol.

This function provides a pointer to a PairList element representing the binding of a symbol. In this variant the pointer is const, and consequently the calling code can use it only to examine the binding.

Parameters:
symbolThe Symbol for which a mapping is sought.
Returns:
A pointer to the required binding, or a null pointer if it was not found..

Implemented in CXXR::StdFrame.

virtual BindingRange CXXR::Frame::bindingRange ( ) const
pure virtual

Obtain a BindingRange for this Frame.

Returns:
a BindingRange allowing read-only iteration over the Binding objects within this Frame.

Implemented in CXXR::StdFrame.

void CXXR::Frame::clear ( )

Remove all symbols from the Frame.

Raises an error if the Frame is locked.

virtual Frame* CXXR::Frame::clone ( ) const
pure virtual

Return pointer to a copy of this Frame.

This function creates a copy of this Frame, and returns a pointer to that copy. The copy will define the same mapping from Symbols to R objects as this Frame; neither the R objects, nor of course the Symbols, are copied as part of the cloning.

The created copy will be locked if this Frame is locked. However, it will not have a read or write monitor.

Returns:
a pointer to a clone of this Frame.
Note:
Derived classes should exploit the covariant return type facility to return a pointer to the type of object being cloned.

Implemented in CXXR::StdFrame.

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

void CXXR::Frame::enableReadMonitoring ( bool  on) const

Enable monitored reading of Symbol values.

This function determines whether the read monitor function set with setReadMonitor() will be called whenever a Symbol's value is read from a Binding within this Frame.

In the case of an active Binding, the monitor is called whenever the encapsulated function is accessed: note that this includes calls to Binding::assign().

Parameters:
onTrue if monitoring is be enabled (in which case a read monitor must already have been set), false if it is to be disabled.
Note:
Whether or not monitoring is enabled is not considered to be part of the state of a Frame object, and hence this function is const.
void CXXR::Frame::enableWriteMonitoring ( bool  on) const

Enable monitored writing of Symbol values.

This function determines whether the write monitor function set with setWriteMonitor() will be called whenever a Symbol's value is modified a Binding within this Frame.

In the case of an active Binding, the monitor is called only when the encapsulated function is initially set or changed: in particular the monitor is not invoked by calls to Binding::assign().

The monitor is not called when a Binding is newly created within a Frame (with the Symbol bound by default to a null pointer).

Parameters:
onTrue if monitoring is be enabled (in which case a write monitor must already have been set), false if it is to be disabled.
Note:
Whether or not monitoring is enabled is not considered to be part of the state of a Frame object, and hence this function is const.
bool CXXR::Frame::erase ( const Symbol symbol)

Remove the Binding (if any) of a Symbol.

This function causes any Binding for a specified Symbol to be removed from the Frame.

An error is raised if the Frame is locked (whether or not it contains a binding of symbol ).

Parameters:
symbolThe Symbol for which the Binding is to be removed.
Returns:
true iff the environment previously contained a mapping for symbol.
bool CXXR::Frame::isLocked ( ) const
inline

Is the Frame locked?

Returns:
true iff the Frame is locked.
void CXXR::Frame::lock ( bool  lock_bindings)
inline

Lock this Frame.

Locking a Frame prevents the addition or removal of Bindings. Optionally, the existing bindings can be locked, preventing them from being modified.

This operation is permitted even if the Frame is already locked, but will have no effect unless it newly locks the Bindings in the Frame.

Parameters:
lock_bindingstrue iff all the existing Bindings in the Frame are to be locked.
virtual void CXXR::Frame::lockBindings ( )
pure virtual

Lock all Bindings in this Frame.

This operation affects only Bindings currently existing. It does not prevent Bindings being added subsequently, and such Bindings will not be locked.

It is permitted to apply this function to a locked Frame.

Implemented in CXXR::StdFrame.

Binding* CXXR::Frame::obtainBinding ( const Symbol symbol)

Get or create a Binding for a Symbol.

If the Frame already contains a Binding for a specified Symbol, the function returns it. Otherwise a Binding to the null pointer is created, and a pointer to that Binding returned.

An error is raised if a new Binding needs to be created and the Frame is locked.

Parameters:
symbolThe Symbol for which a Binding is to be obtained.
Returns:
Pointer to the required Binding.
static monitor CXXR::Frame::setReadMonitor ( monitor  new_monitor)
inlinestatic

Define function to monitor reading of Symbol values.

This function allows the user to define a function to be called whenever a Symbol's value is read from a Binding within a Frame. Even if such a function has been defined, the monitoring is off by default: it must be enabled for particular Frame objects by calling enableReadMonitoring(). See the description of enableReadMonitoring() for further information.

Parameters:
new_monitorPointer, possibly null, to the new monitor function. A null pointer signifies that no read monitoring is to take place, which is the default state.
Returns:
Pointer, possibly null, to the monitor being displaced by new_monitor.
static monitor CXXR::Frame::setWriteMonitor ( monitor  new_monitor)
inlinestatic

Define function to monitor writing of Symbol values.

This function allows the user to define a function to be called whenever a Symbol's value is modified in a Binding within a Frame. Even if such a function has been defined, the monitoring is off by default: it must be enabled for particular Frame objects by calling enableWriteMonitoring(). See the description of enableWriteMonitoring() for further information.

Parameters:
new_monitorPointer, possibly null, to the new monitor function. A null pointer signifies that no read monitoring is to take place, which is the default state.
Returns:
Pointer, possibly null, to the monitor being displaced by new_monitor.
virtual std::size_t CXXR::Frame::size ( ) const
pure virtual

Number of Bindings in Frame.

Returns:
the number of Symbols for which Bindings exist in this Frame.

Implemented in CXXR::StdFrame.

void CXXR::Frame::statusChanged ( const Symbol sym)
inlineprotected

Report change in the bound/unbound status of Symbol objects.

This function should be called when a Symbol that was not formerly bound within this Frame becomes bound, or vice versa. If called with a null pointer, this signifies that all bindings are about to be removed from the Frame.

std::vector<const Symbol*> CXXR::Frame::symbols ( bool  include_dotsymbols) const

Symbols bound by this Frame.

Parameters:
include_dotsymbolsIf false, any Symbol whose name begins with '.' will not be included in the result.
Returns:
A vector containing pointers to the Symbol objects bound by this Frame.
void CXXR::Frame::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: