ple_defs.h File Reference

#include "ple_config.h"
#include <stdarg.h>
#include <stdlib.h>

Go to the source code of this file.

Macros
#define	PLE_ABS(a)   ((a) < 0 ? -(a) : (a)) /* Absolute value of a */
#define	PLE_MIN(a, b)   ((a) > (b) ? (b) : (a)) /* Minimum of a et b */
#define	PLE_MAX(a, b)   ((a) < (b) ? (b) : (a)) /* Maximum of a et b */
#define	PLE_MALLOC(_ptr, _ni, _type)
	Allocate memory for _ni elements of type _type. More...
#define	PLE_REALLOC(_ptr, _ni, _type)
	Reallocate memory for _ni elements of type _type. More...
#define	PLE_FREE(_ptr)   _ptr = ple_mem_free(_ptr, #_ptr, __FILE__, __LINE__)
	Free allocated memory. More...
#define	PLE_MPI_TAG   (int)('P'+'L'+'E') /* MPI tag for PLE operations */
#define	PLE_MPI_LNUM   MPI_INT /* MPI type for ple_lnum_t type */
#define	PLE_MPI_COORD   MPI_DOUBLE /* MPI type for ple_coord_t type */
#define	PLE_UNUSED(x)   (void)(x)
#define	PLE_BEGIN_C_DECLS
#define	PLE_END_C_DECLS
#define	PLE_BEGIN_EXAMPLE_SCOPE   {
#define	PLE_END_EXAMPLE_SCOPE   }

Typedefs
typedef int	ple_lnum_t
typedef double	ple_coord_t
typedef int()	ple_printf_t(const char *const format, va_list arg_ptr)
typedef void()	ple_error_handler_t(const char *file_name, const int line_num, const int sys_error_code, const char *format, va_list arg_ptr)
typedef void *()	ple_mem_malloc_t(size_t ni, size_t size, const char *var_name, const char *file_name, int line_num)
typedef void *()	ple_mem_realloc_t(void *ptr, size_t ni, size_t size, const char *var_name, const char *file_name, int line_num)
typedef void *()	ple_mem_free_t(void *ptr, const char *var_name, const char *file_name, int line_num)

Functions
int	ple_printf (const char *const format,...)
	Replacement for printf() with modifiable behavior. More...
ple_printf_t *	ple_printf_function_get (void)
	Returns function associated with the ple_printf() function. More...
void	ple_printf_function_set (ple_printf_t *f)
	Associates a vprintf() type function with the ple_printf() function. More...
void	ple_error (const char *file_name, const int line_num, const int sys_error_code, const char *format,...)
	Calls the error handler (set by ple_error_handler_set() or default). More...
ple_error_handler_t *	ple_error_handler_get (void)
	Returns the error handler associated with the ple_error() function. More...
void	ple_error_handler_set (ple_error_handler_t *handler)
	Associates an error handler with the ple_error() function. More...
void *	ple_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 *	ple_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 *	ple_mem_free (void *ptr, const char *var_name, const char *file_name, int line_num)
	Free allocated memory. More...
void	ple_mem_functions_get (ple_mem_malloc_t **malloc_func, ple_mem_realloc_t **realloc_func, ple_mem_free_t **free_func)
	Return the function pointers associated with PLE's memory management. More...
void	ple_mem_functions_set (ple_mem_malloc_t *malloc_func, ple_mem_realloc_t *realloc_func, ple_mem_free_t *free_func)
	Associate functions to modifiy PLE's memory management. More...
double	ple_timer_wtime (void)
	Return Wall clock time. More...
double	ple_timer_cpu_time (void)
	Return CPU time. More...

Macro Definition Documentation

PLE_ABS

#define PLE_ABS

(

a

)

((a) < 0 ? -(a) : (a)) /* Absolute value of a */

PLE_BEGIN_C_DECLS

#define PLE_BEGIN_C_DECLS

PLE_BEGIN_EXAMPLE_SCOPE

#define PLE_BEGIN_EXAMPLE_SCOPE   {

PLE_END_C_DECLS

#define PLE_END_C_DECLS

PLE_END_EXAMPLE_SCOPE

#define PLE_END_EXAMPLE_SCOPE   }

PLE_FREE

PLE_FREE

(

_ptr

)

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

Free allocated memory.

This macro calls ple_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.

PLE_MALLOC

PLE_MALLOC	(		_ptr,
			_ni,
			_type
	)

Value:

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

Allocate memory for _ni elements of type _type.

This macro calls ple_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.

PLE_MAX

#define PLE_MAX	(		a,
			b
	)		((a) < (b) ? (b) : (a)) /* Maximum of a et b */

PLE_MIN

#define PLE_MIN	(		a,
			b
	)		((a) > (b) ? (b) : (a)) /* Minimum of a et b */

PLE_MPI_COORD

#define PLE_MPI_COORD   MPI_DOUBLE /* MPI type for ple_coord_t type */

PLE_MPI_LNUM

#define PLE_MPI_LNUM   MPI_INT /* MPI type for ple_lnum_t type */

PLE_MPI_TAG

#define PLE_MPI_TAG   (int)('P'+'L'+'E') /* MPI tag for PLE operations */

PLE_REALLOC

PLE_REALLOC	(		_ptr,
			_ni,
			_type
	)

Value:

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

Reallocate memory for _ni elements of type _type.

This macro calls ple_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.

PLE_UNUSED

#define PLE_UNUSED

(

x

)

(void)(x)

Typedef Documentation

ple_coord_t

typedef double ple_coord_t

ple_error_handler_t

typedef void() ple_error_handler_t(const char *file_name, const int line_num, const int sys_error_code, const char *format, va_list arg_ptr)

ple_lnum_t

typedef int ple_lnum_t

ple_mem_free_t

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

ple_mem_malloc_t

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

ple_mem_realloc_t

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

ple_printf_t

typedef int() ple_printf_t(const char *const format, va_list arg_ptr)

Function Documentation

ple_error()

void ple_error	(	const char *const	file_name,
		const int	line_num,
		const int	sys_error_code,
		const char *const	format,
			...
	)

Calls the error handler (set by ple_error_handler_set() or default).

With the default error handler, an error message is output to stderr, and the current process exits with an EXIT_FAILURE code.

Parameters

[in]	file_name	name of source file from which error handler called.
[in]	line_num	line of source file from which error handler called.
[in]	sys_error_code	error code if error in system or libc call, 0 otherwise.
[in]	format	format string, as printf() and family.
[in]	...	variable arguments based on format string.

ple_error_handler_get()

ple_error_handler_t* ple_error_handler_get

(

void

)

Returns the error handler associated with the ple_error() function.

Returns

pointer to the error handler function.

ple_error_handler_set()

void ple_error_handler_set

(

ple_error_handler_t *

handler

)

Associates an error handler with the ple_error() function.

Parameters

[in]

handler

pointer to the error handler function.

ple_mem_free()

void* ple_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 ple_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, ple_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.

ple_mem_functions_get()

void ple_mem_functions_get	(	ple_mem_malloc_t **	malloc_func,
		ple_mem_realloc_t **	realloc_func,
		ple_mem_free_t **	free_func
	)

Return the function pointers associated with PLE's memory management.

All arguments are optional.

Parameters

[out]	malloc_func	pointer to ple_mem_malloc function pointer (or NULL).
[out]	realloc_func	pointer to ple_mem_realloc function pointer (or NULL).
[out]	free_func	pointer to ple_mem_free function pointer (or NULL).

ple_mem_functions_set()

void ple_mem_functions_set	(	ple_mem_malloc_t *	malloc_func,
		ple_mem_realloc_t *	realloc_func,
		ple_mem_free_t *	free_func
	)

Associate functions to modifiy PLE's memory management.

All arguments are optional, so the previously set functions pointers will not be modified if an argument value is NULL.

Parameters

[in]	malloc_func	ple_mem_malloc function pointer (or NULL).
[in]	realloc_func	ple_mem_realloc function pointer (or NULL).
[in]	free_func	ple_mem_free function pointer (or NULL).

ple_mem_malloc()

void* ple_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 ple_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.

ple_mem_realloc()

void* ple_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 ple_error() errorhandler if it fails to allocate the required memory.

Parameters

[in]	ptr	pointer to previous memory location (if NULL, ple_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.

ple_printf()

int ple_printf	(	const char *const	format,
			...
	)

Replacement for printf() with modifiable behavior.

This function calls vprintf() by default, or a function with similar arguments indicated by ple_printf_function_set().

Parameters

[in]	format	format string, as printf() and family.
[in]	...	variable arguments based on format string.

Returns

number of characters printed, not counting the trailing '\0' used to end output strings

ple_printf_function_get()

ple_printf_t* ple_printf_function_get

(

void

)

Returns function associated with the ple_printf() function.

Returns

pointer to the vprintf() or replacement function.

ple_printf_function_set()

void ple_printf_function_set

(

ple_printf_t *const

fct

)

Associates a vprintf() type function with the ple_printf() function.

Parameters

[in]

fct

pointer to a vprintf() type function.

ple_timer_cpu_time()

double ple_timer_cpu_time

(

void

)

Return CPU time.

Note that in the rare case that only the minimal C library clock() method is available (see ple_timer_cpu_time_method()), at least one of the ple_timer_...() functions (possibly this one) must be called upon program start for this function to be used. In addition, in this case, time may "loop" back to 0 every multiple of 2^size_t / CLOCKS_PER_SEC seconds.

Returns

current CPU time usage, or -1 if unable to compute.

ple_timer_wtime()

double ple_timer_wtime

(

void

)

Return Wall clock time.

Returns

elapsed time from first call of a function of the ple_timer_...() series, or -1 if unable to compute.