Class to select and call to S3 methods. More...

#include <S3Launcher.hpp>

Inheritance diagram for CXXR::S3Launcher:

Collaboration diagram for CXXR::S3Launcher:

Public Member Functions
void	addMethodBindings (Frame *frame) const
	Add the special S3 method bindings to a Frame.
const StringVector *	classes () const
	Vector of classes.
String *	className () const
	Name of method's class.
FunctionBase *	function () const
	Function implementing the method.
std::size_t	locInClasses () const
	Class for which method was found.
Symbol *	symbol () const
	Method name as Symbol.
bool	usingClass () const
	Was a class-specific method found?
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 S3Launcher *	create (RObject object, std::string generic, std::string group, Environment call_env, Environment *table_env, bool allow_default)
	Attempt to create an S3Launcher object.
static std::pair< FunctionBase *, bool >	findMethod (const Symbol symbol, Environment call_env, Environment *table_env)
	Search for an S3 method.
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::GCNode
virtual	~GCNode ()
Protected Member Functions inherited from CXXR::HeterogeneousListBase::Link
virtual	~Link ()

Detailed Description

Class to select and call to S3 methods.

This class provides facilities for selecting an S3 method to call according to the object to be dispatched on, and for setting up the call to the S3 method.

Member Function Documentation

void S3Launcher::addMethodBindings ( Frame * frame ) const

Add the special S3 method bindings to a Frame.

This function adds to frame the special bindings of .Class, .Generic, .GenericCallEnv, .GenericDefEnv, .Method and where appropriate .Group needed for an S3 method call.

Beware that the resulting binding of .Method will not be appropriate for methods of the Ops group.

Parameters:

frame Non-null pointer to the Frame to which Bindings are to be added.

const StringVector* CXXR::S3Launcher::classes ( ) const

inline

Vector of classes.

Returns:: Pointer to the vector of classes associated with the dispatch object.

String* CXXR::S3Launcher::className ( ) const

inline

Name of method's class.

Returns:: pointer to the name of the class to which this method corresponds, or a null pointer if no class-specific method was found.

S3Launcher * S3Launcher::create	(	RObject *	object,
		std::string	generic,
		std::string	group,
		Environment *	call_env,
		Environment *	table_env,
		bool	allow_default
	)

static

Attempt to create an S3Launcher object.

Parameters:

object	Pointer, possibly null, to the object to be dispatched on. The search for a method will work in turn through this object's vector of classes until a method is found. (This vector will be empty if object is null.)
generic	Name of the generic function for which a method is sought.
group	Name of the function group for which a method is sought. Within each `class` in the classes vector, the function first looks for a function called generic`.class` and then, if there is none, for a function called group`.class`, before moving on if necessary to the next element of the classes vector. group may be an empty string, in which case group methods are not considered.
call_env	Non-null pointer to the Environment in which the search for a Binding is first carried out. In practice this will be the call Environment of the S3 generic.
table_env	Pointer, possibly null, to the Environment in whose Frame an S3 methods table (i.e. an Environment bound to `.__S3MethodsTable__.`) is sought, if no method was found in call_env. If table_env is null, no S3 methods table is sought.
allow_default	true iff the function should look for a function called generic`.default` if no class-specific method was found.

Returns:: A null pointer if no suitable S3 method was found, or a pointer to an S3Launcher object for the method found.

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

std::pair< FunctionBase *, bool > S3Launcher::findMethod	(	const Symbol *	symbol,
		Environment *	call_env,
		Environment *	table_env
	)

static

Search for an S3 method.

This function searches for a definition of an S3 method bound to symbol.

The search is first carried out in call_env and its enclosing environments, as in findFunction().

If this fails to find a binding of symbol to a FunctionBase, and table_env is not null, the search then determines whether the Frame of table_env defines an S3 methods table, that is to say, whether it contains a Binding of the symbol .__S3MethodsTable__. to an Environment. If so, a Binding of symbol is sought in the Frame of that Environment (i.e. the Environment bound to .__S3MethodsTable__.). If the value of the Binding is a Promise, the Promise is forced and the result of evaluating the Promise is used as part of the returned value.

If, in the course of searching for a suitable Binding, a Binding of symbol to Symbol::missingArgument() (R_MissingArg) is encountered, an error is raised.

Read/write monitors are invoked in the following circumstances: (i) If a Promise is forced, any read monitor for the relevant Binding is called before forcing it, and any write monitor for the symbol's Binding is called immediately afterwards. (ii) If this function succeeds in finding a Binding to a FunctionBase, then any read monitor for that Binding is called.

Parameters:

symbol	Non-null pointer to the Symbol for which a Binding is sought. In practice the name of the Symbol will be of an articulated form such as `print.lm` or `summary.default`; however, the function neither checks nor relies on this.
call_env	Non-null pointer to the Environment in which the search for a Binding is first carried out. In practice this will be the call Environment of the S3 generic.
table_env	Pointer, possibly null, to the Environment in whose Frame an S3 methods table (i.e. an Environment bound to `.__S3MethodsTable__.`) is sought, if no method was found in call_env. If table_env is null, no S3 methods table is sought.

Returns:: If a Binding to a FunctionBase was found, the first element of the pair is the value of the Binding (except that if the value was a Promise, the first element is the result of evaluating the Promise) and the second element of the pair is true if the Binding was found by searching in call_env, and false if it was found in the S3 methods table. If no Binding to a FunctionBase was found, the first element of the pair will be null and the second element false.

Note:: An S3 methods table is currently sought only within the Frame of table_env itself; the search does not proceed to enclosing Environments. This follows CR, but it perhaps unduly restrictive.

FunctionBase* CXXR::S3Launcher::function ( ) const

inline

Function implementing the method.

Returns:: Pointer to the function implementing the method found.

std::size_t CXXR::S3Launcher::locInClasses ( ) const

inline

Class for which method was found.

Returns:: the location (counting from zero) within the classes() vector to which this S3 method corresponds.

Symbol* CXXR::S3Launcher::symbol ( ) const

inline

Method name as Symbol.

Returns:: pointer to the Symbol containing the name of the method found.

bool CXXR::S3Launcher::usingClass ( ) const

inline

Was a class-specific method found?

Returns:: true iff the method found corresponds to a specific class (whose name will be given by className() ) rather than being a default method.

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

S3Launcher.hpp ($Id: S3Launcher.hpp 1348 2013-02-25 17:49:03Z arr $)
objects.cpp ($Id: objects.cpp 1348 2013-02-25 17:49:03Z arr $)
S3Launcher.cpp ($Id: S3Launcher.cpp 1348 2013-02-25 17:49:03Z arr $)

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Member Function Documentation