Mapping from Symbols to R objects. More...

#include <Environment.h>

Inheritance diagram for CXXR::Environment:

Collaboration diagram for CXXR::Environment:

Classes
class	LoopScope
	Object authorising R 'break' and 'next' commands. More...
class	ReturnScope
	Object authorising R 'return' command. More...

Public Member Functions
	Environment (Environment enclosing, Frame frame)
	Constructor.
bool	canReturn () const
	Is R 'return' currently legal?
Environment *	enclosingEnvironment () const
	Access the enclosing Environment.
std::pair< Environment , Frame::Binding >	findBinding (const Symbol *symbol)
	Search for a Binding for a Symbol.
std::pair< const Environment , const Frame::Binding >	findBinding (const Symbol *symbol) const
	Search for a Binding for a Symbol (const variant).
Frame *	frame ()
	Access the Environment's Frame.
const Frame *	frame () const
	Access the Environment's Frame (const variant).
bool	loopActive () const
	Is R 'break' or 'next' currently legal?
void	maybeDetachFrame ()
	Disconnect the Environment from its Frame, if safe.
const StringVector *	namespaceSpec () const
	Get namespace spec (if applicable).
const StringVector *	packageName () const
	Get package name (if any).
void	setEnclosingEnvironment (Environment *new_enclos)
	Replace the enclosing environment.
void	setSingleStepping (bool on)
	Set single-stepping status.
bool	singleStepping () const
	Get single-stepping status.
void	slotBehind (Environment *anchor)
	Interpolate this Environment between a given Environment and its enclosing Environment.
void	skipEnclosing ()
	Grandparent becomes parent.
unsigned int	packGPBits () const
	Reproduce the `gp` bits field used in CR.
const char *	typeName () const
	Name within R of this type of object.
void	unpackGPBits (unsigned int gpbits)
	Interpret the `gp` bits field used in CR.
void	visitReferents (const_visitor *v) const
	Conduct a visitor to the nodes referred to by this one.
Public Member Functions inherited from CXXR::RObject
virtual const PairList *	attributes () const
	Get object attributes.
virtual void	clearAttributes ()
	Remove all attributes.
virtual RObject *	clone () const
	Return pointer to a copy of this object.
void	copyAttribute (const Symbol name, const RObject source)
	Copy an attribute from one RObject to another.
void	copyAttributes (const RObject *source, bool copyS4)
	Copy attributes from one RObject to another.
virtual RObject *	evaluate (Environment *env)
	Evaluate object in a specified Environment.
virtual RObject *	getAttribute (const Symbol *name) const
	Get the value a particular attribute.
virtual bool	hasAttributes () const
	Has this object any attributes?
bool	hasClass () const
	Has this object the class attribute?
bool	isS4Object () const
	Is this an S4 object?
void	maybeTraceMemory (const RObject *src)
	Carry out memory tracing.
void	maybeTraceMemory (const RObject src1, const RObject src2)
	Carry out memory tracing.
void	maybeTraceMemory (const RObject src1, const RObject src2, const RObject *src3)
	Carry out memory tracing.
bool	memoryTraced () const
	Is copying etc. of this object being traced?
virtual void	setAttribute (const Symbol name, RObject value)
	Set or remove an attribute.
void	setAttributes (const PairList *new_attributes)
	Replace the attributes of an object.
void	setMemoryTracing (bool on)
	Enable/disable tracing of copying etc.
void	setS4Object (bool on)
	Set the status of this RObject as an S4 object.
SEXPTYPE	sexptype () const
	Get an object's SEXPTYPE.
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 Environment *	base ()
	Base environment.
static Environment *	baseNamespace ()
	Base namespace.
static Environment *	empty ()
	Empty environment.
static Environment *	findNamespace (const StringVector *spec)
	Locate a namespace environment from its specification.
static Environment *	findPackage (const std::string &name)
	Locate a package environment from its name.
static Environment *	global ()
	Global environment.
static void	monitorLeaks (const GCNode *node)
	Look for Environment objects that may have 'leaked'.
static const char *	staticTypeName ()
	The name by which this type is known in R.
Static Public Member Functions inherited from CXXR::RObject
template<class T >
static T *	clone (const T *pattern)
	Return a pointer to a copy of an object.
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	detachReferents ()
	Null out all references from this node to other nodes.
Protected Member Functions inherited from CXXR::RObject
	RObject (SEXPTYPE stype=CXXSXP)
	RObject (const RObject &pattern)
	Copy constructor.
Protected Member Functions inherited from CXXR::GCNode
virtual	~GCNode ()
Protected Member Functions inherited from CXXR::HeterogeneousListBase::Link
virtual	~Link ()

Friends
class	boost::serialization::access
class	SchwarzCounter< Environment >
class	Frame

Additional Inherited Members
Public Attributes inherited from CXXR::RObject
unsigned char	m_named
unsigned	m_missing: 2
unsigned	m_argused: 2
bool	m_active_binding: 1
bool	m_binding_locked: 1

Detailed Description

Mapping from Symbols to R objects.

An Environment has an associated Frame, which defines a mapping from (pointers to) CXXR::Symbol objects to (pointers to) arbitrary objects of classes derived from RObject. An Environment will normally have an 'enclosing environment', and the Environment class provides facilities for searching for a binding for a Symbol first in the Environment's own Frame, and then successively in the Frames of enclosing Environments.

Note:: This class does not in itself enforce the requirement that the enclosing relationship must be acyclic.

Todo:: For provenance-tracking, there ought to be some way of monitoring the event that the program fails to find a binding for a Symbol.

Constructor & Destructor Documentation

CXXR::Environment::Environment	(	Environment *	enclosing,
		Frame *	frame
	)

inline

Constructor.

Parameters:

enclosing	Pointer to the enclosing environment.
frame	Pointer to the Frame to be used by the constructed Environment.

Member Function Documentation

static Environment* CXXR::Environment::base ( )

inlinestatic

Base environment.

Returns:: Pointer to the base environment.

static Environment* CXXR::Environment::baseNamespace ( )

inlinestatic

Base namespace.

Returns:: Pointer to the base namespace.

bool CXXR::Environment::canReturn ( ) const

inline

Is R 'return' currently legal?

Returns:: true iff there is currently at least one ReturnScope object in existence associated with this Environment, so that a transfer of control using ReturnException will succeed.

void Environment::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::RObject.

static Environment* CXXR::Environment::empty ( )

inlinestatic

Empty environment.

CR accords a special status to the empty environment, R_EmptyEnv, which is an Environment whose Frame contains no Bindings, and which has no enclosing Environment. In CR the search for a Symbol Binding terminates when it reaches the empty environment, without looking inside it. In CXXR, although the empty environment still exists (for backwards compatibility)), it is not handled specially. If the search for a Symbol reaches the empty environment, CXXR will look for the Symbol inside it - unsuccessfully of course - and the search then terminates because there is no enclosing Environment.

Returns:: Pointer to the empty environment.

Note:: CXXR's own code does not include tests to prohibit the creation of bindings within the empty environment, but the effect of doing so is undefined.

Environment* CXXR::Environment::enclosingEnvironment ( ) const

inline

Access the enclosing Environment.

Returns:: pointer to the enclosing Environment.

pair< Environment *, Frame::Binding * > Environment::findBinding ( const Symbol * symbol )

Search for a Binding for a Symbol.

The search starts in this Environment; if no Binding is found there, the search will proceed through successive enclosing Environments.

Parameters:

symbol Pointer to the Symbol for which a Binding is sought.

Returns:: The first element of the pair is a pointer to the sought Binding, or a null pointer if no Binding was found. The second element of the pair is a pointer to the Environment in whose frame the Binding was found, or a null pointer if no Binding was found.

std::pair<const Environment*, const Frame::Binding*> CXXR::Environment::findBinding ( const Symbol * symbol ) const

inline

Search for a Binding for a Symbol (const variant).

The search starts in this Environment; if no Binding is found there, the search will proceed through successive enclosing Environments.

Parameters:

symbol Pointer to the Symbol for which a Binding is sought.

Returns:: The first element of the pair is a pointer to the Environment in whose frame the Binding was found, or a null pointer if no Binding was found. The second element of the pair is a pointer to the sought Binding, or a null pointer if no Binding was found.

Environment * Environment::findNamespace ( const StringVector * spec )

static

Locate a namespace environment from its specification.

Parameters:

spec	Non-null pointer to the specification of a namespace environment (as returned by namespaceSpec() ).

Returns:: A pointer to the namespace environment corresponding to spec . This namespace is loaded if necessary, and deserialization fails if loading is unsuccessful.

Todo:: Having deserialization fail entirely in the event that the namespace cannot be loaded seems insufficiently robust, but follows CR practice.

Environment * Environment::findPackage ( const std::string & name )

static

Locate a package environment from its name.

Parameters:

name	Name of a package, prefixed by `package:`.

Returns:: A pointer to the package environment corresponding to name . This package is loaded if necessary. If loading fails, the function returns a pointer to the global Environment (Environment::global()): this follows CR practice.

Frame* CXXR::Environment::frame ( )

inline

Access the Environment's Frame.

Returns:: pointer to the Environment's Frame.

const Frame* CXXR::Environment::frame ( ) const

inline

Access the Environment's Frame (const variant).

Returns:: const pointer to the Environment's Frame.

static Environment* CXXR::Environment::global ( )

inlinestatic

Global environment.

Returns:: Pointer to the global environment.

bool CXXR::Environment::loopActive ( ) const

inline

Is R 'break' or 'next' currently legal?

Returns:: true iff there is currently at least one LoopScope object in existence associated with this Environment.

void CXXR::Environment::maybeDetachFrame ( )

inline

Disconnect the Environment from its Frame, if safe.

Just before the application of a Closure returns, this function is called on the local Environment of the Closure. If it appears that the Environment will no longer be reachable after the Closure returns (i.e., the Environment is not 'leaked'), it detaches the Environment from its Frame. This breaks possible loops in the GCNode/GCEdge graph, thus enabling the Environment to be garbage-collected immediately.

Note:: This function is an inlined no-op unless the preprocessor variable DETACH_LOCAL_FRAMES is defined in Environment.h.

static void CXXR::Environment::monitorLeaks ( const GCNode * node )

inlinestatic

Look for Environment objects that may have 'leaked'.

This function determines if any Environment objects are reachable from node, and if so marks them as 'leaked'. It is called in respect of any objects that are 'exported' from a Closure call, for example the return value of the call, and the objects of any non-local assignments within the call.

Parameters:

node	Pointer (possibly null) to the object to be scrutinised.

Note:: This function is an inlined no-op unless the preprocessor variable DETACH_LOCAL_FRAMES is defined in Environment.h.

const StringVector * Environment::namespaceSpec ( ) const

Get namespace spec (if applicable).

Returns:: If this Environment is a namespace environment, this function returns the namespace specification. Otherwise returns a null pointer.

const StringVector * Environment::packageName ( ) const

Get package name (if any).

Returns:: If this Environment is the Environment of a package, this function returns the name of the package (of the form "package:foo") as the first element of a StringVector. Otherwise returns a null pointer.

unsigned int Environment::packGPBits ( ) const

virtual

Reproduce the gp bits field used in CR.

This function is used to reproduce the sxpinfo_struct.gp field used in CR. It should be used exclusively for serialization. Refer to the 'R Internals' document for details of this field.

Returns:: the reconstructed gp bits field (within the least significant 16 bits).

Note:: If this function is overridden in a derived class, the overriding function should call packGPBits() for its immediate base class, and then 'or' further bits into the result.

Reimplemented from CXXR::RObject.

void Environment::setEnclosingEnvironment ( Environment * new_enclos )

Replace the enclosing environment.

Parameters:

new_enclos Pointer to the environment now to be considered to enclose this Environment.

Deprecated:: Retained for use in deserialization and in the R function parent.env<- (itself deprecated). For other purposes, use instead slotBehind() and skipEnclosing(), which ensure that the 'enclosing' relationship remains acyclic.

void CXXR::Environment::setSingleStepping ( bool on )

inline

Set single-stepping status.

Parameters:

on	The required single-stepping status (true = enabled).

bool CXXR::Environment::singleStepping ( ) const

inline

Get single-stepping status.

Returns:: true if debugger should single-step within this Environment.

void Environment::skipEnclosing ( )

Grandparent becomes parent.

Suppose that prior to the call, E is the enclosing Environment of this Environment (it is an error for E to be null), and that EE (possibly null) is the enclosing Environment of E. Then after the call EE will be the enclosing Environment both of this Environment and of E. (However, this change may expose E to garbage collection.)

void Environment::slotBehind ( Environment * anchor )

Interpolate this Environment between a given Environment and its enclosing Environment.

This causes this Environment T to be interpolated between anchor and the current enclosing Environment of anchor. Suppose that prior to the call E (possibly null) is the enclosing Environment of anchor. Then after the call, E will be the enclosing Environment of T, and T will be the enclosing Environment of anchor.

Parameters:

anchor Pointer to the Environment 'behind' which this Environment is to be interpolated. Must not be a null pointer.

static const char* CXXR::Environment::staticTypeName ( )

inlinestatic

The name by which this type is known in R.

Returns:: The name by which this type is known in R.

const char * Environment::typeName ( ) const

virtual

Name within R of this type of object.

Returns:: the name by which this type of object is known within R.

Reimplemented from CXXR::RObject.

void Environment::unpackGPBits ( unsigned int gpbits )

virtual

Interpret the gp bits field used in CR.

This function is used to interpret the sxpinfo_struct.gp field used in CR in a way appropriate to a particular node class. It should be used exclusively for deserialization. Refer to the 'R Internals' document for details of this field.

Parameters:

gpbits the gp bits field (within the least significant 16 bits).

Note:: If this function is overridden in a derived class, the overriding function should also pass its argument to unpackGPBits() for its immediate base class.

Reimplemented from CXXR::RObject.

void Environment::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::RObject.

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

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation