Allocation & Deallocation

Parallel-protected debugging-enhanced wrapper around system malloc(). More...

Collaboration diagram for Allocation & Deallocation:

Files
file	malloc.h

Data Structures
struct	bu_pool

Macros
#define	BU_PAGE_SIZE   4096
#define	BU_GET(_ptr, _type)   _ptr = (_type *)bu_calloc(1, sizeof(_type), #_type " (BU_GET) " CPP_FILELINE)
#define	BU_PUT(_ptr, _type)   do { *(uint8_t *)(_type *)(_ptr) = /*zap*/ 0; bu_free(_ptr, #_type " (BU_PUT) " CPP_FILELINE); _ptr = NULL; } while (0)
#define	BU_ALLOC(_ptr, _type)   _ptr = (_type *)bu_calloc(1, sizeof(_type), #_type " (BU_ALLOC) " CPP_FILELINE)
#define	BU_FREE(_ptr, _type)   do { bu_free(_ptr, #_type " (BU_FREE) " CPP_FILELINE); _ptr = (_type *)NULL; } while (0)

Typedefs
typedef int(*	bu_heap_func_t) (const char *,...)

Functions
void *	bu_malloc (size_t siz, const char *str)
void *	bu_calloc (size_t nelem, size_t elsize, const char *str)
void	bu_free (void *ptr, const char *str)
void *	bu_realloc (void *ptr, size_t siz, const char *str)
int	bu_malloc_len_roundup (int nbytes)
void *	bu_heap_get (size_t sz)
void	bu_heap_put (void *ptr, size_t sz)
bu_heap_func_t	bu_heap_log (bu_heap_func_t log)
struct bu_pool *	bu_pool_create (size_t block_size)
void *	bu_pool_alloc (struct bu_pool *pool, size_t nelem, size_t elsize)
void	bu_pool_delete (struct bu_pool *pool)
int	bu_shmget (int *shmid, char **shared_memory, int key, size_t size)

Variables
size_t	bu_n_malloc
size_t	bu_n_realloc
size_t	bu_n_free

Detailed Description

Parallel-protected debugging-enhanced wrapper around system malloc().

Provides a parallel-safe interface to the system memory allocator with standardized error checking, optional memory-use logging, and optional run-time pointer and memory corruption testing.

The bu_*alloc() routines can't use bu_log() because that uses the bu_vls() routines which depend on bu_malloc(). So it goes direct to stderr, semaphore protected.

Macro Definition Documentation

BU_PAGE_SIZE

#define BU_PAGE_SIZE   4096

Compilation constant for a page of memory.

This is basically intended to be the minimum size for a contiguous block of virtual memory that hopefully, but not necessarily, aligns with or is a smaller evenly divisible fraction of the operating system's virtual memory page size. We could look page size up at runtime but the primary purpose of this define is to help routines using static memory buffers for processing pick a fixed array size.

Definition at line 70 of file malloc.h.

BU_GET

#define BU_GET	(		_ptr,
			_type
	)		_ptr = (_type *)bu_calloc(1, sizeof(_type), #_type " (BU_GET) " CPP_FILELINE)

Fast dynamic memory allocation macro for small pointer allocations. Memory is automatically initialized to zero and, similar to bu_calloc(), is guaranteed to return non-NULL (or bu_bomb()).

Memory acquired with BU_GET() should be returned with BU_PUT(), NOT with bu_free().

Use BU_ALLOC() for dynamically allocating structures that are relatively large, infrequently allocated, or otherwise don't need to be fast.

Definition at line 226 of file malloc.h.

BU_PUT

#define BU_PUT	(		_ptr,
			_type
	)		do { *(uint8_t *)(_type *)(_ptr) = /*zap*/ 0; bu_free(_ptr, #_type " (BU_PUT) " CPP_FILELINE); _ptr = NULL; } while (0)

Handy dynamic memory deallocator macro. Deallocated memory has the first byte zero'd for sanity (and potential early detection of double-free crashing code) and the pointer is set to NULL.

Memory acquired with bu_malloc()/bu_calloc() should be returned with bu_free(), NOT with BU_PUT().

Definition at line 240 of file malloc.h.

BU_ALLOC

#define BU_ALLOC	(		_ptr,
			_type
	)		_ptr = (_type *)bu_calloc(1, sizeof(_type), #_type " (BU_ALLOC) " CPP_FILELINE)

Convenience macro for allocating a single structure on the heap. Not intended for performance-critical code. Release memory acquired with bu_free() or BU_FREE() to dealloc and set NULL.

Definition at line 248 of file malloc.h.

BU_FREE

#define BU_FREE	(		_ptr,
			_type
	)		do { bu_free(_ptr, #_type " (BU_FREE) " CPP_FILELINE); _ptr = (_type *)NULL; } while (0)

Convenience macro for deallocating a single structure allocated on the heap (with bu_malloc(), bu_calloc(), BU_ALLOC()).

Definition at line 254 of file malloc.h.

Typedef Documentation

bu_heap_func_t

typedef int(* bu_heap_func_t) (const char *,...)

Convenience typedef for the printf()-style callback function used during application exit to print summary statistics.

Definition at line 172 of file malloc.h.

Function Documentation

bu_malloc()

void * bu_malloc	(	size_t	siz,
		const char *	str
	)

This routine only returns on successful allocation. We promise never to return a NULL pointer; caller doesn't have to check. Allocation failure results in bu_bomb() being called.

Referenced by Serializer::Serializer(), and Serializer::take().

bu_calloc()

void * bu_calloc	(	size_t	nelem,
		size_t	elsize,
		const char *	str
	)

This routine only returns on successful allocation. We promise never to return a NULL pointer; caller doesn't have to check. Failure results in bu_bomb() being called.

bu_free()

void bu_free	(	void *	ptr,
		const char *	str
	)

Free dynamically allocated memory.

This routine releases memory allocated by bu_malloc(), bu_calloc(), or bu_realloc(). An optional 'str' string will be written out to stderr if there is an error. NULL pointers are silently ignored. Caller book-keeping may set pointers to -1L to detect invalid calls to bu_free().

bu_free() intentionally wipes out the first four bytes pointed to by ptr prior to releasing memory as a basic memory safeguard. All bits are set to one (0xFFFFFFFF). This is intended to wipe out any magic number in structures and provide a distinct memory signature if the address happens to be accessed via some other pointer. While not guaranteed after memory is released, many implementations leave the value intact which can help with debugging.

bu_realloc()

void * bu_realloc	(	void *	ptr,
		size_t	siz,
		const char *	str
	)

bu_malloc()/bu_free() compatible wrapper for realloc().

this routine mimics the C99 standard behavior of realloc() except that NULL will never be returned. it will bomb if siz is zero and ptr is NULL. it will return a minimum allocation suitable for bu_free() if siz is zero and ptr is non-NULL.

While the string 'str' is provided for the log messages, don't disturb the str value, so that this storage allocation can be tracked back to its original creator.

bu_malloc_len_roundup()

int bu_malloc_len_roundup

(

int

nbytes

)

On systems with the CalTech malloc(), the amount of storage ACTUALLY ALLOCATED is the amount requested rounded UP to the nearest power of two. For structures which are acquired and released often, this works well, but for structures which will remain unchanged for the duration of the program, this wastes as much as 50% of the address space (and usually memory as well). Here, we round up a byte size to the nearest power of two, leaving off the malloc header, so as to ask for storage without wasting any.

On systems with the traditional malloc(), this strategy will just consume the memory in somewhat larger chunks, but overall little unused memory will be consumed.

bu_heap_get()

void * bu_heap_get

(

size_t

sz

)

really fast heap-based memory allocation intended for "small" allocation sizes (e.g., single structs).

the implementation allocates chunks of memory ('pages') in order to substantially reduce calls to system malloc. it has a nice property of having O(1) constant time complexity and profiles significantly faster than system malloc().

release memory with bu_heap_put() only.

Referenced by PooledObject< T >::operator new().

bu_heap_put()

void bu_heap_put	(	void *	ptr,
		size_t	sz
	)

counterpart to bu_heap_get() for releasing fast heap-based memory allocations.

the implementation may do nothing, relying on free-on-exit, or may mark deallocations for reuse. pass a NULL pointer and zero size to force compaction of any unused memory.

Referenced by PooledObject< T >::operator delete().

bu_heap_log()

bu_heap_func_t bu_heap_log

(

bu_heap_func_t

log

)

This function registers and returns the current printing function that will be used during application exit (via an atexit() handler) if the BU_HEAP_PRINT environment variable is set. Statistics on calls to bu_heap_get() and bu_heap_put() will be logged. If log is NULL, the currently set function will remain unchanged and will be returned.

bu_pool_create()

struct bu_pool * bu_pool_create

(

size_t

block_size

)

bu_pool_alloc()

void * bu_pool_alloc	(	struct bu_pool *	pool,
		size_t	nelem,
		size_t	elsize
	)

bu_pool_delete()

void bu_pool_delete

(

struct bu_pool *

pool

)

bu_shmget()

int bu_shmget	(	int *	shmid,
		char **	shared_memory,
		int	key,
		size_t	size
	)

Attempt to get shared memory - returns -1 if new memory was created, 0 if successfully returning existing memory, and 1 if the attempt failed.

Variable Documentation

bu_n_malloc

size_t bu_n_malloc

extern

bu_n_realloc

size_t bu_n_realloc

extern

bu_n_free

size_t bu_n_free

extern