Environment.h File Reference

($Id: Environment.h 1390 2013-06-11 14:41:41Z arr $)

Class CXXR::Environment and associated C interface. More...

#include "CXXR/RObject.h"
#include <boost/serialization/access.hpp>
#include <boost/serialization/base_object.hpp>
#include <boost/serialization/nvp.hpp>
#include "CXXR/Frame.hpp"
#include "CXXR/GCStackRoot.hpp"
#include "CXXR/Symbol.h"

Include dependency graph for Environment.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	CXXR::Environment
	Mapping from Symbols to R objects. More...
class	CXXR::Environment::LoopScope
	Object authorising R 'break' and 'next' commands. More...
class	CXXR::Environment::ReturnScope
	Object authorising R 'return' command. More...

Namespaces
namespace	CXXR
	Namespace for the CXXR project.

Macros
#define	DETACH_LOCAL_FRAMES

Functions
std::pair< Environment *, FunctionBase * >	CXXR::findFunction (const Symbol *symbol, Environment *env, bool inherits=true)
	Search for a Binding of a Symbol to a FunctionBase.
template<typename UnaryPredicate >
std::pair< Environment *, RObject * >	CXXR::findTestedValue (const Symbol *symbol, Environment *env, UnaryPredicate pred, bool inherits)
	Search for a Binding whose value satisfies a predicate.
template<class Archive >
void	boost::serialization::load_construct_data (Archive &ar, CXXR::Environment *t, const unsigned int version)
	Template specialisation.
Rboolean	Rf_isEnvironment (SEXP s)
	Is this a CXXR::Environment?
SEXP	ENCLOS (SEXP x)
	Access enclosing environment.
Rboolean	ENV_DEBUG (SEXP x)
	Should the debugger single-step?
SEXP	FRAME (SEXP x)
	Access an environment's Frame, represented as a PairList.
void	SET_ENV_DEBUG (SEXP x, Rboolean v)
	Enable/disable single-stepping of the debugger.
void	SET_SYMVALUE (SEXP x, SEXP val)
	Set symbol's value in the base environment.
SEXP	SYMVALUE (SEXP x)
	Symbol's value in the base environment.

Variables
SEXP	R_EmptyEnv
SEXP	R_BaseEnv
SEXP	R_GlobalEnv
SEXP	R_BaseNamespace

---

Detailed Description

Class CXXR::Environment and associated C interface.

---

Macro Definition Documentation

#define DETACH_LOCAL_FRAMES

If the preprocessor variable DETACH_LOCAL_FRAMES is defined, then code is inserted which keeps track of whether the local Environment of a Closure application may continue to be reachable after the Closure application returns. If not, then just before the Closure application returns, the Environment is detached from its Frame. This breaks possible loops in the GCNode/GCEdge graph, thus enabling the Environment to be garbage-collected immediately.

Unfortunately, enabling this extra code slows CXXR down very slightly; however, it may prove beneficial in the future when combined with provenance tracking.

---

Function Documentation

SEXP ENCLOS ( SEXP  x )

inline

Access enclosing environment.

Parameters:

x	Pointer to a CXXR::Environment (checked).

Returns:

Pointer to the enclosing environment of x .

Rboolean ENV_DEBUG ( SEXP  x )

inline

Should the debugger single-step?

Parameters:

x	Pointer to a CXXR::Environment object (checked).

Returns:

true if single-stepping is set, i.e. the debugger should single-step within this environment.

SEXP FRAME ( SEXP  x )

inline

Access an environment's Frame, represented as a PairList.

Parameters:

x	Pointer to a CXXR::Environment (checked).

Returns:

Pointer to a PairList representing the contents of the Frame of x (may be null). This PairList is generated on the fly, so this is a relatively expensive operation. Alterations to the returned PairList will not alter the Environment's Frame.

Note:

Beware that since (unlike CR) this isn't a simple accessor function, its return value will need protection from garbage collection.

Rboolean Rf_isEnvironment ( SEXP  s )

inline

Is this a CXXR::Environment?

Parameters:

s	Pointer to an RObject.

Returns:

TRUE iff the RObject pointed to by s is an environment.

void SET_ENV_DEBUG ( SEXP  x, Rboolean  v  )

inline

Enable/disable single-stepping of the debugger.

Parameters:

x	Pointer a CXXR::Environment object (checked).
v	The new single-stepping state (true = enabled).

void SET_SYMVALUE ( SEXP  x, SEXP  val  )

inline

Set symbol's value in the base environment.

Parameters:

x	Pointer to a CXXR::Symbol (checked).
val	Pointer to the RObject now to be considered as the value of this symbol. A null pointer or R_UnboundValue are permissible values of val.

Todo:

No binding to R_UnboundValue ought to be created.

SEXP SYMVALUE ( SEXP  x )

inline

Symbol's value in the base environment.

Parameters:

x	Pointer to a CXXR::Symbol (checked).

Returns:

Pointer to a CXXR::RObject representings x's value. Returns R_UnboundValue if no value is currently associated with the Symbol.