bft_mem.h File Reference

#include "cs_defs.h"
#include "bft_error.h"

Include dependency graph for bft_mem.h:

Go to the source code of this file.

Macros
#define	BFT_MALLOC(_ptr, _ni, _type)
	Allocate memory for _ni elements of type _type. More...
#define	BFT_REALLOC(_ptr, _ni, _type)
	Reallocate memory for _ni elements of type _type. More...
#define	BFT_FREE(_ptr)   _ptr = bft_mem_free(_ptr, #_ptr, __FILE__, __LINE__)
	Free allocated memory. More...
#define	BFT_MEMALIGN(_ptr, _align, _ni, _type)
	Allocate aligned memory for _ni elements of type _type. More...

Functions
void	bft_mem_init (const char *log_file_name)
	Initialize memory handling. More...
void	bft_mem_end (void)
	End memory handling. More...
int	bft_mem_initialized (void)
	Indicates if bft_mem_...() functions are initialized. More...
void *	bft_mem_malloc (size_t ni, size_t size, const char *var_name, const char *file_name, int line_num)
	Allocate memory for ni elements of size bytes. More...
void *	bft_mem_realloc (void *ptr, size_t ni, size_t size, const char *var_name, const char *file_name, int line_num)
	Reallocate memory for ni elements of size bytes. More...
void *	bft_mem_free (void *ptr, const char *var_name, const char *file_name, int line_num)
	Free allocated memory. More...
void *	bft_mem_memalign (size_t alignment, size_t ni, size_t size, const char *var_name, const char *file_name, int line_num)
	Allocate aligned memory for ni elements of size bytes. More...
size_t	bft_mem_size_current (void)
	Return current theoretical dynamic memory allocated. More...
size_t	bft_mem_size_max (void)
	Return maximum theoretical dynamic memory allocated. More...
int	bft_mem_have_memalign (void)
	Indicate if a memory aligned allocation variant is available. More...
bft_error_handler_t *	bft_mem_error_handler_get (void)
	Returns the error handler associated with the bft_mem_...() functions. More...
void	bft_mem_error_handler_set (bft_error_handler_t *handler)
	Associates an error handler with the bft_mem_...() functions. More...

Macro Definition Documentation

BFT_FREE

BFT_FREE

(

_ptr

)

_ptr = bft_mem_free(_ptr, #_ptr, __FILE__, __LINE__)

Free allocated memory.

This macro calls bft_mem_free(), automatically setting the allocated variable name and source file name and line arguments.

The freed pointer is set to NULL to avoid accidental reuse.

Parameters

[in,out]

_ptr

pointer to allocated memory.

BFT_MALLOC

BFT_MALLOC	(		_ptr,
			_ni,
			_type
	)

Value:

_ptr = (_type *) bft_mem_malloc(_ni, sizeof(_type), \
                                #_ptr, __FILE__, __LINE__)

Allocate memory for _ni elements of type _type.

This macro calls bft_mem_malloc(), automatically setting the allocated variable name and source file name and line arguments.

Parameters

[out]	_ptr	pointer to allocated memory.
[in]	_ni	number of elements.
[in]	_type	element type.

BFT_MEMALIGN

BFT_MEMALIGN	(		_ptr,
			_align,
			_ni,
			_type
	)

Value:

_ptr = (_type *) bft_mem_memalign(_align, _ni, sizeof(_type), \
                                  #_ptr, __FILE__, __LINE__)

Allocate aligned memory for _ni elements of type _type.

This macro calls bft_mem_memalign(), automatically setting the allocated variable name and source file name and line arguments.

Parameters

[out]	_ptr	pointer to allocated memory.
[in]	_align	alignment.
[in]	_ni	number of elements.
[in]	_type	element type.

BFT_REALLOC

BFT_REALLOC	(		_ptr,
			_ni,
			_type
	)

Value:

_ptr = (_type *) bft_mem_realloc(_ptr, _ni, sizeof(_type), \
                                 #_ptr, __FILE__, __LINE__)

Reallocate memory for _ni elements of type _type.

This macro calls bft_mem_realloc(), automatically setting the allocated variable name and source file name and line arguments.

Parameters

[in,out]	_ptr	pointer to allocated memory.
[in]	_ni	number of elements.
[in]	_type	element type.

Function Documentation

bft_mem_end()

void bft_mem_end

(

void

)

End memory handling.

This function should be called after all other bft_mem_...() functions. In case of memory allocation logging, it writes final information to the log file and closes is.

bft_mem_error_handler_get()

bft_error_handler_t* bft_mem_error_handler_get

(

void

)

Returns the error handler associated with the bft_mem_...() functions.

Returns

pointer to the error handler function.

bft_mem_error_handler_set()

void bft_mem_error_handler_set

(

bft_error_handler_t *

handler

)

Associates an error handler with the bft_mem_...() functions.

With the default error handler, an error message is output to stderr, (after bft_print_flush() is called), and the general error handler used by bft_error() is then called (which results in the termination of the current process or process group).

Parameters

handler

pointer to the error handler function [in].

bft_mem_free()

void* bft_mem_free	(	void *	ptr,
		const char *	var_name,
		const char *	file_name,
		int	line_num
	)

Free allocated memory.

This function calls free(), but adds tracing capabilities, and automatically calls the bft_error() errorhandler if it fails to free the corresponding memory. In case of a NULL pointer argument, the function simply returns.

Parameters

[in]	ptr	pointer to previous memory location (if NULL, bft_alloc() called).
[in]	var_name	allocated variable name string
[in]	file_name	name of calling source file
[in]	line_num	line number in calling source file

Returns

NULL pointer.

bft_mem_have_memalign()

int bft_mem_have_memalign

(

void

)

Indicate if a memory aligned allocation variant is available.

If no such function is available, bft_mem_memalign() will always fail.

Returns

1 if memory aligned allocation is possible, 0 otherwise.

bft_mem_init()

void bft_mem_init

(

const char *

log_file_name

)

Initialize memory handling.

This function should be called before any other bft_mem_...() function. To activate memory allocation logging, a logfile name should be given as an argument. The resulting file will be a regular, local file. If this file cannot be opened for some reason, logging is silently de-activated.

Parameters

log_file_name

name of optional log_file (if NULL, no log).

bft_mem_initialized()

int bft_mem_initialized

(

void

)

Indicates if bft_mem_...() functions are initialized.

Returns

1 if bft_mem_init has been called, 0 otherwise.

bft_mem_malloc()

void* bft_mem_malloc	(	size_t	ni,
		size_t	size,
		const char *	var_name,
		const char *	file_name,
		int	line_num
	)

Allocate memory for ni elements of size bytes.

This function calls malloc(), but adds tracing capabilities, and automatically calls the bft_error() errorhandler if it fails to allocate the required memory.

Parameters

[in]	ni	number of elements.
[in]	size	element size.
[in]	var_name	allocated variable name string.
[in]	file_name	name of calling source file.
[in]	line_num	line number in calling source file.

Returns

pointer to allocated memory.

bft_mem_memalign()

void* bft_mem_memalign	(	size_t	alignment,
		size_t	ni,
		size_t	size,
		const char *	var_name,
		const char *	file_name,
		int	line_num
	)

Allocate aligned memory for ni elements of size bytes.

This function calls posix_memalign() if available, but adds tracing capabilities, and automatically calls the bft_error() errorhandler if it fails to allocate the required memory.

The associated function bft_mem_have_memalign() indicates if this type of allocation may be used on this system.

Parameters

[in]	alignment	alignment.
[in]	ni	number of elements.
[in]	size	element size.
[in]	var_name	allocated variable name string.
[in]	file_name	name of calling source file.
[in]	line_num	line number in calling source file.

Returns

pointer to allocated memory.

bft_mem_realloc()

void* bft_mem_realloc	(	void *	ptr,
		size_t	ni,
		size_t	size,
		const char *	var_name,
		const char *	file_name,
		int	line_num
	)

Reallocate memory for ni elements of size bytes.

This function calls realloc(), but adds tracing capabilities, and automatically calls the bft_error() errorhandler if it fails to allocate the required memory.

Parameters

[in]	ptr	pointer to previous memory location (if NULL, bft_alloc() called).
[in]	ni	number of elements.
[in]	size	element size.
[in]	var_name	allocated variable name string.
[in]	file_name	name of calling source file.
[in]	line_num	line number in calling source file.

Returns

pointer to reallocated memory.

bft_mem_size_current()

size_t bft_mem_size_current

(

void

)

Return current theoretical dynamic memory allocated.

Returns

current memory handled through bft_mem_...() (in kB).

bft_mem_size_max()

size_t bft_mem_size_max

(

void

)

Return maximum theoretical dynamic memory allocated.

Returns

maximum memory handled through bft_mem_...() (in kB).