CXXR (C++ R)
Classes | Namespaces | Typedefs | Functions
ProtectStack.h File Reference

($Id: ProtectStack.h 1397 2013-08-16 18:25:59Z arr $)

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

#include "CXXR/RObject.h"
#include "CXXR/NodeStack.hpp"
Include dependency graph for ProtectStack.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

class  CXXR::ProtectStack
 Class implementing CR's 'pointer protection stack'. More...
class  CXXR::ProtectStack::Scope
 Object constraining lifetime of ProtectStack entries. More...

Namespaces

namespace  CXXR
 Namespace for the CXXR project.

Typedefs

typedef unsigned int PROTECT_INDEX

Functions

void R_ProtectWithIndex (SEXP node, PROTECT_INDEX *iptr)
 Push a node pointer onto the C pointer protection stack.
void R_Reprotect (SEXP node, PROTECT_INDEX index)
 Retarget a cell in the C pointer protection stack.
void Rf_ppsRestoreSize (size_t new_size)
 Restore C pointer protection stack to a previous size.
size_t Rf_ppsSize ()
 Current size of C pointer protection stack.
SEXP Rf_protect (SEXP node)
 Push a node pointer onto the C pointer protection stack.
void Rf_unprotect (int count)
 Pop cells from the C pointer protection stack.
void Rf_unprotect_ptr (SEXP node)
 Remove entry from pointer protection stack.

Detailed Description

Class CXXR::ProtectStack and associated C interface.

CXXR::ProtectStack encapsulates the functionality of the CR pointer protection stack.

See the paragraph 'Caller Protects' in the description of class CXXR::GCStackRoot for recommended coding policy.


Function Documentation

void R_ProtectWithIndex ( SEXP  node,
PROTECT_INDEX *  iptr 
)
inline

Push a node pointer onto the C pointer protection stack.

Push a node pointer onto the C pointer protection stack, and record the index of the resulting stack cell (for subsequent use with R_Reprotect).

Parameters:
nodePointer to the node to be protected from the garbage collector.
iptrPointer to a location in which the stack cell index is to be stored.
void R_Reprotect ( SEXP  node,
PROTECT_INDEX  index 
)
inline

Retarget a cell in the C pointer protection stack.

Change the node that a particular cell in the C pointer protection stack protects. As a consistency check, it is required that the reprotect takes place within the same ProtectStack::Scope as the original 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 R_ProtectWithIndex() ) of the stack cell to be retargeted to node. Must be less than the current size of the C pointer protection stack.
void Rf_ppsRestoreSize ( size_t  new_size)

Restore C pointer protection stack to a previous size.

Restore the C pointer protection stack to a previous size by popping elements off the top.

Parameters:
new_sizeThe size to which the stack is to be restored. Must not be greater than the current size.
Deprecated:
This is an interface for C code to call CXXR::ProtectStack::restoreSize(), which may cease to be available in future. In C++, use of the ProtectStack::Scope class is preferable.
size_t Rf_ppsSize ( )

Current size of C pointer protection stack.

Returns:
the current size of the C pointer protection stack.
Deprecated:
This is an interface for C code to call CXXR::ProtectStack::size(), which may cease to be public in future.
SEXP Rf_protect ( SEXP  node)
inline

Push a node pointer onto the C pointer protection stack.

Parameters:
nodePointer to the node to be protected from the garbage collector.
Returns:
a copy of node .
void Rf_unprotect ( int  count)
inline

Pop cells from the C pointer protection stack.

As a consistency check, it is required that the unprotect takes place within the same ProtectStack::Scope as the corresponding protects.

Parameters:
countNumber of cells to be popped. Must not be larger than the current size of the C pointer protection stack.
void Rf_unprotect_ptr ( SEXP  node)
inline

Remove entry from pointer protection stack.

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

Parameters:
nodePointer to the node whose cell is to be removed from the C pointer protection stack.
Deprecated:
Utterly.