RAllocStack.h File Reference

($Id: RAllocStack.h 1348 2013-02-25 17:49:03Z arr $)

Function R_alloc() and kin. More...

#include <stddef.h>
#include <stack>
#include <vector>
#include "CXXR/config.hpp"
#include "CXXR/SchwarzCounter.hpp"

Include dependency graph for RAllocStack.h:

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

Go to the source code of this file.

Classes
class	CXXR::RAllocStack
	Class for implementing R_alloc() and kindred functions. More...
class	CXXR::RAllocStack::Scope
	Object constraining lifetime of R_alloc() blocks. More...

Namespaces
namespace	CXXR
	Namespace for the CXXR project.

Functions
char *	R_alloc (size_t num_elts, int elt_size)
	Allocate a block of memory.
void *	CXXR_alloc (size_t num_elts, int elt_size)
	Allocate a block of memory.
char *	S_alloc (long num_elts, int elt_size)
	Allocate a block of memory, and initialize it to zero.
char *	S_realloc (char *prev_block, long new_sz, long old_sz, int elt_size)
	Reallocate a block of memory.
void *	vmaxget (void)
	Number of memory blocks allocated.
void	vmaxset (const void *stack_sizep)
	Reclaims memory blocks.

---

Detailed Description

Function R_alloc() and kin.

Defines functions R_alloc() and related functions, and the class CXXR::RAllocStack which is used to implement them.

---

Function Documentation

void* CXXR_alloc ( size_t  num_elts, int  elt_size  )

inline

Allocate a block of memory.

This is a wrapper round R_alloc() for the use of former CR code that is now treated as C++. It differs from R_alloc() in returning void* rather than char*, thus allowing conversion to the required pointer type to be achieved by static_cast rather than reinterpret_cast.

Parameters:

num_elts	Number of data items to be accommodated in the block.
elt_size	Size in bytes (strictly, as a multiple of sizeof(char)) of each data item. Must be non-negative.

Returns:

Pointer to the start of the memory block.

Deprecated:

For use only as described above. The function is not accessible from C, and new C++ code should use C++ memory allocation mechanisms (i.e. new/delete).

char* R_alloc	(	size_t	num_elts,
		int	elt_size
	)

Allocate a block of memory.

This function is provided primarily for the use of code called from the R .C function. It will allocate a block of memory that will automatically be reclaimed by R at the end of the .C call.

Parameters:

num_elts	Number of data items to be accommodated in the block.
elt_size	Size in bytes (strictly, as a multiple of sizeof(char)) of each data item. Must be non-negative.

Returns:

Pointer to the start of the memory block.

Note:

The signed type of elt_size is anomalous, but is part of the R API.

char* S_alloc	(	long	num_elts,
		int	elt_size
	)

Allocate a block of memory, and initialize it to zero.

This is part of the S compatibility interface. It does the same thing as R_alloc(), except that the memory block is guaranteed to be initialized to zero.

Parameters:

num_elts	Number of data items to be accommodated in the block. Must be non-negative.
elt_size	Size in bytes (strictly, as a multiple of sizeof(char)) of each data item. Must be non-negative.

Returns:

Pointer to the start of the memory block.

char* S_realloc	(	char *	prev_block,
		long	new_sz,
		long	old_sz,
		int	elt_size
	)

Reallocate a block of memory.

This is part of the S compatibility interface, and is used when it is decided that a block of memory previously allocated by S_alloc() or S_realloc() needs to be expanded. It allocates a new block of memory, copies across the previous contents, and zeroes any additional elements.

Parameters:

prev_block	Pointer to a block of memory previously allocated by S_alloc() or S_realloc().
new_sz	New number of elements (>= 0) to be accommodated.
old_sz	Number of elements contained in prev_block.
elt_size	Size in bytes (strictly, as a multiple of sizeof(char)) of each data item. Must be non-negative.

Returns:

Pointer to the start of the newly allocated memory block. If new_sz <= old_sz, the function does not allocate a new block, and simply returns prev_block.

void* vmaxget ( void  )

inline

Number of memory blocks allocated.

Returns:

The current number of blocks allocated via R_alloc(), S_alloc() and S_realloc(), coerced into a char* for compatibility with CR. (This function and vmaxset() are declared in the R.h API.)

Note:

C++ code should preferably use the CXXR::RAllocStack::Scope class instead. It is possible that in the future this function will always return a null pointer.

void vmaxset ( const void *  stack_sizep )

inline

Reclaims memory blocks.

Parameters:

stack_sizep

A value previously returned by a call to vmaxget(). vmaxset() will reclaim the memory from all blocks allocated via R_alloc(), S_alloc() and S_realloc() subsequent to that call of vmaxget().

Deprecated:

For expert use only. C++ code should preferably use the CXXR::RAllocStack::Scope class instead. It is possible that in the future this function will become a no-op.