CXXR (C++ R)
Macros
config.hpp File Reference

($Id: config.hpp 1406 2013-09-20 08:14:25Z arr $)

Build configuration options specific to CXXR. More...

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

Go to the source code of this file.

Macros

#define AGGRESSIVE_GC
#define AGGRESSIVE_GC
#define CELLFIFO
 First-in first-out memory block allocation.
#define CHECK_EXPOSURE
 Check that CXXR::GCNode objects are exposed to garbage collection.
#define CHECK_EXPOSURE
 Check that CXXR::GCNode objects are exposed to garbage collection.
#define FILL55
 Fill deallocated memory blocks with 0x55.
#define FILL55
 Fill deallocated memory blocks with 0x55.
#define GCID
 Give CXXR::GCNode objects serial numbers.
#define GCID
 Give CXXR::GCNode objects serial numbers.
#define NDEBUG
 Suppress some runtime checks.
#define RARE_GC
 Suppress reference-counting garbage collection.
#define UNCHECKED_SEXP_DOWNCAST
 Don't check downcasts within the CXXR::RObject class hierarchy.

Detailed Description

Build configuration options specific to CXXR.

This file contains documentation and definitions of preprocessor variables that configure the behaviour of CXXR. However, it excludes preprocessor variables that are controlled by options to the autoconf-generated configure script: for information on these see ./configure –help.

As distributed, this file represents a configuration suitable for development, with numerous facilities enable for checking and debugging. For maximum speed, it is recommended that this file be modified by enabling the definitions of NDEBUG and UNCHECKED_SEXP_DOWNCAST, and disabling all other definitions.


Macro Definition Documentation

#define AGGRESSIVE_GC

By default, GCNode::operator new initiates a reference-count-based garbage collection (GCNode::gclite()) only when the number of bytes allocated has risen by a certain margin from the number allocated after the last such collection. However, if CXXR is compiled with the preprocessor variable AGGRESSIVE_GC define, every call to GCNode::operator new will initiate a reference-count-based garbage collection. When used in conjunction with FILL55, GCID and (optionally) CELLFIFO, this can help to detect and diagnose gaps in the protection of nodes against garbage collection.

#define AGGRESSIVE_GC

By default, GCNode::operator new initiates a reference-count-based garbage collection (GCNode::gclite()) only when the number of bytes allocated has risen by a certain margin from the number allocated after the last such collection. However, if CXXR is compiled with the preprocessor variable AGGRESSIVE_GC define, every call to GCNode::operator new will initiate a reference-count-based garbage collection. When used in conjunction with FILL55, GCID and (optionally) CELLFIFO, this can help to detect and diagnose gaps in the protection of nodes against garbage collection.

#define CELLFIFO

First-in first-out memory block allocation.

By default, class CXXR::CellPool (which class CXXR::MemoryBank uses to manage memory blocks smaller than 128 bytes) operates a last-in-first-out allocation policy; that is to say, if there are memory blocks that have been deallocated and not yet reallocated, the next one to be reallocated will be the one that was most recently deallocated. This makes for efficient utilisation of the processor caches. However, if CXXR is compiled with the preprocessor variable CELLFIFO defined, it instead operates a first-in-first-out policy. This results in a longer turnround time in reallocating cells, which improves the lethality of the FILL55 preprocessor variable (described below) in showing up premature deallocation of cells.

#define CHECK_EXPOSURE

Check that CXXR::GCNode objects are exposed to garbage collection.

Code is inserted to verify that any object of a class derived from CXXR::GCNode has been exposed to garbage-collection before it is made the target of any CXXR::GCEdge, CXXR::GCRoot or CXXR::GCStackRoot smart pointer, or is protected using PROTECT(). The use of this flag is strongly recommended during development.

#define CHECK_EXPOSURE

Check that CXXR::GCNode objects are exposed to garbage collection.

Code is inserted to verify that any object of a class derived from CXXR::GCNode has been exposed to garbage-collection before it is made the target of any CXXR::GCEdge, CXXR::GCRoot or CXXR::GCStackRoot smart pointer, or is protected using PROTECT(). The use of this flag is strongly recommended during development.

#define FILL55

Fill deallocated memory blocks with 0x55.

CXXR::MemoryBank::deallocate() fills the released memory with 0x55 bytes (though some of these may be overwritten by pointers used for free list management). This can be useful in helping to manifest or diagnose premature garbage collection.

#define FILL55

Fill deallocated memory blocks with 0x55.

CXXR::MemoryBank::deallocate() fills the released memory with 0x55 bytes (though some of these may be overwritten by pointers used for free list management). This can be useful in helping to manifest or diagnose premature garbage collection.

#define GCID

Give CXXR::GCNode objects serial numbers.

This causes each object of a class derived from CXXR::GCNode to be given a unique identification number. (Well, unique modulo the wordlength!) This can be useful in debugging problems with premature garbage collection: refer to the comments in GCNode.cpp for hints on how to do this.

#define GCID

Give CXXR::GCNode objects serial numbers.

This causes each object of a class derived from CXXR::GCNode to be given a unique identification number. (Well, unique modulo the wordlength!) This can be useful in debugging problems with premature garbage collection: refer to the comments in GCNode.cpp for hints on how to do this.

#define NDEBUG

Suppress some runtime checks.

By default, CXXR includes code to check that CXXR::GCStackRoot objects are destroyed in the reverse order of creation, and that a node is UNPROTECTed in the same RCNTXT as it was PROTECTed. If NDEBUG is defined, these checks are omitted. Not recommended during development.

#define RARE_GC

Suppress reference-counting garbage collection.

By default, CXXR will delete any CXXR::GCNode whose reference count has fallen to zero as a preliminary to allocating memory for a new CXXR::GCNode. Because the memory of CXXR::GCNode objects thus deleted is likely to be reused almost immediately, it can be difficult to identify bugs caused by premature garbage collection (i.e. insufficient protection against garbage collection). In particular, the FILL55 preprocessor variable is less effective in this regard than it was before CXXR used reference counting. Defining RARE_GC suppresses the default behaviour, and results in CXXR::GCNode objects being deleted only as part of the mark-sweep garbage collection process, initiated when a memory utilisation threshold is exceeded. In summary, if a bug stops manifesting itself when RARE_GC is defined, it is probably due to premature garbage collection.

#define UNCHECKED_SEXP_DOWNCAST

Don't check downcasts within the CXXR::RObject class hierarchy.

By default, CXXR implements the templated function CXXR::SEXP_downcast<PtrOut, PtrIn>() using dynamic_cast, to verify that the argument object is of an appropriate type for the requested cast. If UNCHECKED_SEXP_DOWNCAST is defined, CXXR uses instead a static_cast, i.e. it in effect assumes that the downcast is legal. Not recommended during development.