Replacement for CR's SEXPREC. More...

#include <RObject.h>

Inheritance diagram for CXXR::RObject:

Collaboration diagram for CXXR::RObject:

Classes
struct	DoNothing
	Class of function object that does nothing to an RObject. More...

Public Member Functions
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 unsigned int	packGPBits () const
	Reproduce the `gp` bits field used in CR.
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.
virtual const char *	typeName () const
	Name within R of this type of object.
virtual void	unpackGPBits (unsigned int gpbits)
	Interpret the `gp` bits field used in CR.
void	detachReferents ()
	Null out all references from this node to other nodes.
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
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.

Public Attributes
unsigned char	m_named
unsigned	m_missing: 2
unsigned	m_argused: 2
bool	m_active_binding: 1
bool	m_binding_locked: 1

Protected Member Functions
	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

Detailed Description

Replacement for CR's SEXPREC.

This class is the rough equivalent within CXXR of the SEXPREC union within CR. However, all functionality relating to garbage collection has been factored out into the base class GCNode, and as CXXR development proceeds other functionality will be factored out into derived classes (corresponding roughly, but not exactly, to different SEXPTYPE values within CR), or outside the RObject hierarchy altogether.

Eventually this class may end up simply as the home of R attributes.

Note:: The word 'object' in the name of this class is used in the sense in which the 'blue book' (Becker et al. [1988]) uses the phrase 'data object'. Roughly speaking, CXXR::RObject is a base class for the sorts of data items whose existence would be reported by the R function objects(). In particular, it does not imply that the object belongs to an R class.

Invariant:

The class currently aims to enforce the following invariants in regard to each RObject:

m_has_class is true iff the object has the class attribute.
Each attribute in the list of attributes must have a Symbol as its tag. Null tags are not allowed.
Each attribute must have a distinct tag: no duplicates allowed.
No attribute may have a null value: an attempt to set the value of an attribute to null will result in the removal of the attribute altogether.

The CR code in attrib.cpp applies further consistency conditions on attributes, but these are not yet enforced via the class interface.

const RObject* policy:

There is an inherent tension between the way CR is implemented and the 'const-correctness' that C++ programmers seek, and this particularly arises in connection with pointers to objects of classes derived from RObject. CR accesses such objects exclusively using SEXP, which is a non-const pointer. (The occasional use within the CR code of const SEXP is misguided: the compiler interprets this in effect as RObject* const, not as const RObject*.) One possible policy would be simply never to use const T*, where T is RObject* or a class inheriting from it: that would remove any need for const_casts at the interface between new CXXR code and code inherited from CR. But CXXR tries to move closer to C++ idiom than that, notwithstanding the resulting need for const_casts at the interface, and applies a policy driven by the following considerations:

RObject::evaluate() cannot return a const RObject*, because some functions return a pointer to an Environment, which may well need subsequently to be modified e.g. by inserting or changing bindings.
This in turn means that RObject::evaluate() cannot itself be a const function, because the default implementation returns this. (Another view would be that the default implementation is an elided copy.) Also, Promise objects change internally when they are evaluated (though this might conceivably be swept up by mutable).
It is a moot point whether FunctionBase::apply() can be const. Closure::apply() entails evaluating the body, and if the body is regarded as part of the Closure object, that would point to apply() not being const. (Note that some of the types which Rf_mkCLOSXP() accepts as a Closure body use the default RObject::evaluate(), so Point 2 definitely applies.)
Should PairList objects and suchlike emulate (roughly speaking) (a) list<pair<const RObject*, const RObject*> > (where the first element of the pair is the tag and the second the 'car'), (b) list<pair<const RObject*, RObject*> > or (c) list<pair<RObject*, RObject*> > ? Since the 'cars' of list elements will often need to be evaluated, Point 2 rules out (a). At present CXXR follows (b).
Since Symbol objects may well need to be evaluated, Symbol::obtain() returns a non-const pointer; similarly, String::obtain() returns a non-const pointer to a String object.

Todo:: Incorporate further attribute consistency checks within the class interface. Possibly make setAttribute() virtual so that these consistency checks can be tailored according to the derived class.

Constructor & Destructor Documentation

CXXR::RObject::RObject ( SEXPTYPE stype = CXXSXP )

inlineexplicitprotected

Parameters:

stype Required type of the RObject.

CXXR::RObject::RObject ( const RObject & pattern )

protected

Copy constructor.

Parameters:

pattern Object to be copied.

Member Function Documentation

virtual const PairList* CXXR::RObject::attributes ( ) const

virtual

Get object attributes.

Returns:: Pointer to the attributes of this object.

Note:: Callers should beware that derived classes may override this function with one that gives rise to garbage collection.

virtual RObject* CXXR::RObject::clone ( ) const

inlinevirtual

Return pointer to a copy of this object.

This function creates a copy of this object, and returns a pointer to that copy.

Generally this function (and the copy constructors it utilises) will attempt to create a 'deep' copy of the object; this follows standard practice within C++, and it is intended to extend this practice as CXXR development continues.

However, if the pattern object contains unclonable subobjects, then the created copy will at the relevant places simply contain pointers to those subobjects, i.e. to that extent the copy is 'shallow'. This is managed using the smart pointers defined by nested class RObject::Handle.

Returns:: a pointer to a clone of this object, or a null pointer if this object cannot be cloned.

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

Reimplemented in CXXR::PairList, CXXR::VectorBase, CXXR::FixedVector< T, ST, Initializer >, CXXR::Closure, CXXR::DumbVector< T, ST >, CXXR::Expression, and CXXR::S4Object.

template<class T >

static T* CXXR::RObject::clone ( const T * pattern )

inlinestatic

Return a pointer to a copy of an object.

Template Parameters:

T	RObject or a type derived from RObject.

Parameters:

pattern Either a null pointer or a pointer to the object to be cloned.

Returns:: Pointer to a clone of pattern, or a null pointer if pattern cannot be cloned or is itself a null pointer.

void CXXR::RObject::copyAttribute	(	const Symbol *	name,
		const RObject *	source
	)

inline

Copy an attribute from one RObject to another.

Parameters:

name	Non-null pointer to the Symbol naming the attribute to be copied.
source	Non-null pointer to the object from which the attribute are to be copied. If source does not have an attribute named name , then the function has no effect.

void CXXR::RObject::copyAttributes	(	const RObject *	source,
		bool	copyS4
	)

Copy attributes from one RObject to another.

Any existing attributes of *this are discarded.

Parameters:

source	Non-null pointer to the object from which attributes are to be copied.
copyS4	If true, the status of source as an S4 object (or not) is also copied to *this .

void CXXR::RObject::detachReferents ( )

inlinevirtual

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.

Reimplemented in CXXR::Environment, CXXR::ConsCell, CXXR::Symbol, CXXR::FixedVector< T, ST, Initializer >, CXXR::Closure, CXXR::WeakRef, CXXR::ExternalPointer, CXXR::Promise, and CXXR::HandleVector< T, ST >.

virtual RObject* CXXR::RObject::evaluate ( Environment * env )

virtual

Evaluate object in a specified Environment.

Parameters:

env	Pointer to the environment in which evaluation is to take place.

Returns:: Pointer to the result of evaluation.

Reimplemented in CXXR::Symbol, CXXR::Promise, and CXXR::Expression.

virtual RObject* CXXR::RObject::getAttribute ( const Symbol * name ) const

virtual

Get the value a particular attribute.

Parameters:

name	Pointer to a `Symbol` giving the name of the sought attribute.

Returns:: pointer to the value of the attribute with name, or a null pointer if there is no such attribute.

Note:: Implementers of derived classes should ensure that any function overriding this will not give rise to garbage collection.

virtual bool CXXR::RObject::hasAttributes ( ) const

inlinevirtual

Has this object any attributes?

Returns:: true iff this object has any attributes.

Note:: Implementers of derived classes should ensure that any function overriding this will not give rise to garbage collection.

bool CXXR::RObject::hasClass ( ) const

inline

Has this object the class attribute?

Returns:: true iff this object has the class attribute.

bool CXXR::RObject::isS4Object ( ) const

inline

Is this an S4 object?

Returns:: true iff this is an S4 object.

void CXXR::RObject::maybeTraceMemory ( const RObject * src )

inline

Carry out memory tracing.

This function is a no-op unless CXXR is built with R_MEMORY_PROFILING defined (as will happen if it is configured with –enable-memory-profiling).

This function should be called if this has been created as a copy of src, or if this has been derived in some way from src1. When memory profiling is enabled, if src points to an RObject with the memoryTraced() property set, this property will be propagated to this. Also the creation of this object will be reported, along with the current context stack.

Parameters:

src	Non-null pointer to an RObject.

void CXXR::RObject::maybeTraceMemory	(	const RObject *	src1,
		const RObject *	src2
	)

inline

Carry out memory tracing.

This function is a no-op unless CXXR is built with R_MEMORY_PROFILING defined (as will happen if it is configured with –enable-memory-profiling).

This function should be called if this has been derived in some way from src1 and src2. When memory profiling is enabled, if either src1 or src2 points to an RObject with the memoryTraced() property set, this property will be propagated to this. Also the creation of this object will be reported, along with the current context stack.

Parameters:

src1	Non-null pointer to an RObject.
src2	Non-null pointer to an RObject.

void CXXR::RObject::maybeTraceMemory	(	const RObject *	src1,
		const RObject *	src2,
		const RObject *	src3
	)

inline

Carry out memory tracing.

This function is a no-op unless CXXR is built with R_MEMORY_PROFILING defined (as will happen if it is configured with –enable-memory-profiling).

This function should be called if this has been derived in some way from src1, src2 and src 3. When memory profiling is enabled, if any of src1, src2 or src3 points to an RObject with the memoryTraced() property set, this property will be propagated to this. Also the creation of this object will be reported, along with the current context stack.

Parameters:

src1	Non-null pointer to an RObject.
src2	Non-null pointer to an RObject.
src3	Non-null pointer to an RObject.

bool CXXR::RObject::memoryTraced ( ) const

inline

Is copying etc. of this object being traced?

The property reported by this function is used by R functions such as tracemem, and has effect only if CXXR is built with R_MEMORY_PROFILING defined (as will happen if it is configured with –enable-memory-profiling).

Returns:: A return value of true signifies that when a copy is made of this object, or - more generally - some comparably sized object is derived from this object, this fact should be reported, and the 'memory traced' property propagated to the new object.

virtual unsigned int CXXR::RObject::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 in CXXR::PairList, CXXR::Environment, CXXR::String, and CXXR::WeakRef.

virtual void CXXR::RObject::setAttribute	(	const Symbol *	name,
		RObject *	value
	)

virtual

Set or remove an attribute.

Parameters:

name	Pointer to the Symbol naming the attribute to be set or removed.
value	Pointer to the value to be ascribed to the attribute, or a null pointer if the attribute is to be removed. The object whose attribute is set (i.e. `this`) should be considered to assume ownership of value, which should therefore not be subsequently altered externally.

void CXXR::RObject::setAttributes ( const PairList * new_attributes )

Replace the attributes of an object.

Parameters:

new_attributes Pointer to the start of the new list of attributes. May be a null pointer, in which case all attributes are removed. The object whose attributes are set (i.e. this) should be considered to assume ownership of the 'car' values in new_attributes ; they should therefore not be subsequently altered externally.

Note:: The new_attributes list should conform to the class invariants. However, attributes with null values are silently discarded, and if duplicate attributes are present, only the last one is heeded (and if the last setting has a null value, the attribute is removed altogether).

void CXXR::RObject::setMemoryTracing ( bool on )

inline

Enable/disable tracing of copying etc.

The property set by this function is used by R functions such as tracemem, and has effect only if CXXR is built with R_MEMORY_PROFILING defined (as will happen if it is configured with –enable-memory-profiling).

Parameters:

on	A value of true signifies that when a copy is made of this object, or - more generally - some comparably sized object is derived from this object, this fact should be reported, and the 'memory traced' property propagated to the new object.

void CXXR::RObject::setS4Object ( bool on )

Set the status of this RObject as an S4 object.

Parameters:

on	true iff this is to be considered an S4 object. CXXR raises an error if an attempt is made to unset the S4 object status of an S4Object (S4SXP), whereas CR (at least as of 2.7.2) permits this.

SEXPTYPE CXXR::RObject::sexptype ( ) const

inline

Get an object's SEXPTYPE.

Returns:: SEXPTYPE of this object.

virtual const char* CXXR::RObject::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 in CXXR::PairList, CXXR::Environment, CXXR::BuiltInFunction, CXXR::Symbol, CXXR::String, CXXR::FixedVector< T, ST, Initializer >, CXXR::Closure, CXXR::ExternalPointer, CXXR::Promise, CXXR::HandleVector< T, ST >, CXXR::DumbVector< T, ST >, CXXR::UncachedString, CXXR::CachedString, CXXR::Expression, and CXXR::S4Object.

virtual void CXXR::RObject::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 in CXXR::PairList, CXXR::Environment, and CXXR::WeakRef.

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

Reimplemented in CXXR::Environment, CXXR::ConsCell, CXXR::Symbol, CXXR::FixedVector< T, ST, Initializer >, CXXR::Closure, CXXR::ExternalPointer, CXXR::Promise, and CXXR::HandleVector< T, ST >.

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

RObject.h ($Id: RObject.h 1351 2013-03-08 15:12:28Z arr $)

Classes

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation