CXXR (C++ R)
Classes | Public Member Functions
CXXR::NodeStack Class Reference

Class implementing a stack of RObject*. More...

#include <NodeStack.hpp>

List of all members.

Classes

class  ElementProxy
 Proxy object for an element of a NodeStack. More...
class  Scope
 Object constraining lifetime of NodeStack entries. More...

Public Member Functions

 NodeStack (size_t initial_capacity)
 Constructor.
ElementProxy operator[] (unsigned int index)
 Element access.
RObject *const operator[] (unsigned int index) const
 Read-only element access.
void eraseTopmost (RObject *node)
 Remove topmost cell with given contents.
ElementProxy fromEnd (unsigned int count)
 Element access with respect to stack top.
void pop (unsigned int count=1)
 Pop pointers from the NodeStack.
void protectAll ()
 Ensure GC protection of all nodes.
unsigned int push (RObject *node)
 Push a node pointer onto the NodeStack.
void retarget (RObject *node, unsigned int index)
 Change the target of a pointer on the PPS.
void resize (size_t new_size)
 Modify size of NodeStack.
size_t size () const
 Current size of NodeStack.
RObjecttopnpop ()
 pop and return the top element of the stack.
void visitRoots (GCNode::const_visitor *v)
 Conduct a const visitor via the NodeStack.

Detailed Description

Class implementing a stack of RObject*.

This class is not intended for general use. It is currently used in class ProtectStack and in the bytecode interpreter.

Note that it is necessary for GCNode::gclite() to call the protectAll() method of every NodeStack in existence before it starts to delete nodes with zero references counts.


Constructor & Destructor Documentation

NodeStack::NodeStack ( size_t  initial_capacity)

Constructor.

Parameters:
initial_capacityThe initial capacity of the NodeStack to be created. The capacity will be increased as necessary, so the value of this parameter is not critical.

Member Function Documentation

void NodeStack::eraseTopmost ( RObject node)

Remove topmost cell with given contents.

Removes from the C pointer protection stack the uppermost stack cell containing a specified node address, and drops all the stack cells above it by one place.

If this function is executed within a NodeStack::Scope pertaining to this NodeStack, its execution counts as a 'pop', and must balance a push() previously executed within the innermost such scope. This is checked unless the class is compiled with NDEBUG.

Parameters:
nodePointer value (possibly null) which must be contained in at least one cell within the NodeStack. This cell will be removed from the stack, and any cells above it dropped by one place.
Deprecated:
Used to implement the CR function UNPROTECT_PTR() (itself ghastly). Its use for any other purpose is strongly deprecated.
ElementProxy CXXR::NodeStack::fromEnd ( unsigned int  count)
inline

Element access with respect to stack top.

Parameters:
countA value of 1 signifies the top value of the stack, 2 the element immediately below that, and so on. Must be strictly positive and smaller than the size of the stack (checked unless the class is compiled with NDEBUG).
Returns:
the specified element.
ElementProxy CXXR::NodeStack::operator[] ( unsigned int  index)
inline

Element access.

Parameters:
indexIndex of required element (counting from zero). Bounds checking is applied unless the class is compiled with NDEBUG.
Returns:
Proxy for the specified element, via which the element can be examined or modified.
RObject* const CXXR::NodeStack::operator[] ( unsigned int  index) const
inline

Read-only element access.

Parameters:
indexIndex of required element (counting from zero). Bounds checking is applied unless the class is compiled with NDEBUG.
Returns:
the specified element.
void NodeStack::pop ( unsigned int  count = 1)

Pop pointers from the NodeStack.

If this function is executed within a NodeStack::Scope pertaining to this NodeStack, the number of elements popped must balance a corresponding number of push() operations previously executed within the innermost such scope. This is checked unless the class is compiled with NDEBUG.

Parameters:
countNumber of cells to be popped. Must not be larger than the current size of the C pointer protection stack (checked unless compiled with NDEBUG).
void NodeStack::protectAll ( )

Ensure GC protection of all nodes.

This function ensures that all RObjects pointed to from the NodeStack are protected from garbage collection.

unsigned int CXXR::NodeStack::push ( RObject node)
inline

Push a node pointer onto the NodeStack.

Parameters:
nodePointer, possibly null, to the node to be pushed onto the NodeStack.
Returns:
Index of the stack cell thus created, counting from zero.
void CXXR::NodeStack::resize ( size_t  new_size)
inline

Modify size of NodeStack.

Parameters:
new_sizeThe required size. If larger than the current size, the added cells will contain null pointers. If smaller than the current size, then pointers are popped off the NodeStack to bring its size down to new_size.
void NodeStack::retarget ( RObject node,
unsigned int  index 
)

Change the target of a pointer on the PPS.

Change the node that a particular cell in the C pointer protection stack protects. As a consistency check, it is required that the retarget takes place within the same NodeStack::Scope as the corresponding protect.

Parameters:
nodePointer to the node now to be protected from the garbage collector by the designated stack cell. (Not necessarily a different node from the one currently protected.)
indexIndex (as returned by protect() ) of the stack cell to be retargeted to node. Must be less than the current size of the C pointer protection stack (checked).
size_t CXXR::NodeStack::size ( ) const
inline

Current size of NodeStack.

Returns:
the number of pointers currently on the NodeStack.
RObject* CXXR::NodeStack::topnpop ( )
inline

pop and return the top element of the stack.

The stack must not be empty; this is checked unless the class is compiled with NDEBUG.

Returns:
the pointer previously at the top of the stack.
void NodeStack::visitRoots ( GCNode::const_visitor v)

Conduct a const visitor via the NodeStack.

Conduct a GCNode::const_visitor object to each RObject pointed to by the NodeStack.

Parameters:
vPointer to the const_visitor object.

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