Mapping from Symbols to R objects. More...

#include <Frame.hpp>

Inheritance diagram for CXXR::Frame:

Collaboration diagram for CXXR::Frame:

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.
PairList *	asPairList () const
	Get contents as a PairList.
Binding *	bind (const Symbol symbol, RObject value, Frame::Binding::Origin origin=Frame::Binding::EXPLICIT)
	Bind a Symbol to a specified value.
virtual Binding *	binding (const Symbol *symbol)=0
	Access binding of an already-defined Symbol.
virtual const Binding *	binding (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 Frame *	clone () 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.
Binding *	obtainBinding (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?
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 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 ()
Protected Member Functions inherited from CXXR::HeterogeneousListBase::Link
virtual	~Link ()

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 * 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:

symbol	Non-null pointer to the Symbol to be bound or rebound.
value	Pointer, possibly null, to the RObject to which symbol is now to be bound. Any previous binding of symbol is overwritten.
origin	Origin 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:

symbol The 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, and CXXR::ListFrame.

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:

symbol The 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, and CXXR::ListFrame.

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, and CXXR::ListFrame.

void 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, and CXXR::ListFrame.

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

on	True 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 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:

on	True 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 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:

symbol The 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_bindings true 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, and CXXR::ListFrame.

Frame::Binding * 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:

symbol The 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_monitor Pointer, 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_monitor Pointer, 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, and CXXR::ListFrame.

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.

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

Symbols bound by this Frame.

Parameters:

include_dotsymbols If 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 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:

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:

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation