malloc.h File Reference

Detailed Description

Customized memory allocation macros that provide diagnostic information when out-of-memory errors occur.

The memory allocation macros assume C's 'malloc', 'realloc' and 'free' by default. However, the user may override these by calling oski_SetMalloc(), oski_SetRealloc(), and oski_SetFree(), respectively.

Go to the source code of this file.

Defines

#define INC_OSKI_MALLOC_H
 oski/malloc.h has been included.
#define oski_Malloc(elem_type, num_elems)
 Customized macro for memory allocation.
#define oski_MallocNoError(elem_type, num_elems)
 Customized macro for memory allocation with no error reporting.
#define oski_Realloc(ptr_addr, elem_type, num_elems)
 Customized macro for memory re-allocation.
#define oski_Free(ptr)   oski_FreeInternal( ptr )
 Customized macro for memory release.

Typedefs

typedef void *(* oski_mallocfunc_t )(size_t)
 Type specifying a 'malloc'-compatible function.
typedef void *(* oski_reallocfunc_t )(void *, size_t)
 Type specifying a 'realloc'-compatible function.
typedef void(* oski_freefunc_t )(void *)
 Type specifying a 'free'-compatible function.

Functions

void * oski_MallocInternal (const char *elem_type, size_t elem_size, size_t num_elems, const char *source_file, unsigned long line_number)
 Allocate a block of memory, and call the error handler on error.
int oski_ReallocInternal (void **p_ptr, const char *elem_type, size_t elem_size, size_t num_elems, const char *source_file, unsigned long line_number)
 Reallocate a block of memory, and call the error handler on error.
void oski_FreeInternal (void *ptr)
 Free a previously allocated block of memory.
int oski_MultiMalloc (const char *file, unsigned long line, int k,...)
 Performs multiple memory allocations.
void oski_FreeAll (int k,...)
 Free a list of pointers.
oski_mallocfunc_t oski_GetMalloc (void)
 Returns the current memory allocation function.
oski_reallocfunc_t oski_GetRealloc (void)
 Returns the current memory reallocation routine.
oski_freefunc_t oski_GetFree (void)
 Returns the function used to free allocated memory.
oski_mallocfunc_t oski_SetMalloc (oski_mallocfunc_t new_func)
 Change the current memory allocation function.
oski_reallocfunc_t oski_SetRealloc (oski_reallocfunc_t new_func)
 Change the current memory re-allocation function.
oski_freefunc_t oski_SetFree (oski_freefunc_t new_func)
 Change the function used to free allocated memory.
void oski_ZeroMem (void *buf, size_t num_bytes)
 Zero out bytes in a buffer.

Define Documentation

#define oski_Free (  ptr   )     oski_FreeInternal( ptr )
 

Customized macro for memory release.

Parameters:
ptr Address of object, allocated using oski_Malloc, to free.
This macro frees the given memory block using the current free-memory routine (see oski_GetFree and oski_SetFree).

#define oski_Malloc (  elem_type,
num_elems   ) 
 

Value:

(elem_type *)oski_MallocInternal( \
        #elem_type, sizeof(elem_type), (num_elems), __FILE__, __LINE__ )
Customized macro for memory allocation.

Parameters:
[in] elem_type Type of the element to allocate.
[in] num_elems Number of such elements to allocate.
This macro allocates a block of memory using the current memory allocation routine (see oski_GetMalloc and oski_SetMalloc). This block logically contains num_elems elements, each of type elem_type.

On error, this macro executes the default global error handler with information about the allocation error.

Returns:
Returns pointer to the new block, or NULL on error.

#define oski_MallocNoError (  elem_type,
num_elems   ) 
 

Value:

(elem_type *)oski_MallocInternal( \
        #elem_type, sizeof(elem_type), (num_elems), NULL, -1 )
Customized macro for memory allocation with no error reporting.

This macro is identical to oski_Malloc() except that it does not call the error handler on error.

#define oski_Realloc (  ptr_addr,
elem_type,
num_elems   ) 
 

Value:

oski_ReallocInternal( ptr_addr, #elem_type, sizeof(elem_type), \
        num_elems, __FILE__, __LINE__ )
Customized macro for memory re-allocation.

Parameters:
[in,out] ptr_addr Address of a pointer to an allocated block.
[in] elem_type Type of each element in the block.
[in] num_elems Size of the new block, in elements.
Returns:
If the block can be resized, this routine returns 0 and changes ptr to be equal the starting address of the new block. Otherwise (on error), returns an error code, calls the current handler, and leaves the original memory block unchanged.
Like the C-routine 'realloc', this routine copies as much data as possible from the previous block to the new block.

On error, this routine returns an error code (integer less than 0) and calls the current error handler.

Function Documentation

void oski_FreeInternal (  void *  ptr  ) 
 

Free a previously allocated block of memory.

Parameters:
[in,out] ptr Pointer to block of memory to free, previously created by a call to oski_MallocInternal.
This routine frees the given block of memory only if it is not NULL. Otherwise, no action takes place (and no error is generated).

This routine is for the library's internal use only and should not normally be called directly by users of the library.

Postcondition:
ptr is no longer usable.

void* oski_MallocInternal (  const char *  elem_type,
size_t  elem_size,
size_t  num_elems,
const char *  source_file,
unsigned long  line_number
) 
 

Allocate a block of memory, and call the error handler on error.

Parameters:
[in] elem_type Name of the type of element being allocated (descriptive string).
[in] elem_size Size of each element, in bytes.
[in] num_elems Number of such elements to allocate.
[in] source_file Source file of the caller (for debugging).
[in] line_number Line number at which the call is being made (for debugging).
Returns:
A pointer to the newly allocated and zeroed block, or NULL on error.
This routine is for the library's internal use only and should not normally be called directly by users of the library.

If source_file == NULL, then this routine does not call the error handler on failure.

int oski_MultiMalloc (  const char *  file,
unsigned long  line,
int  k,
  ...
) 
 

Performs multiple memory allocations.

Returns a 0 and pointers to all allocated buffers on success. Otherwise, returns an error code and allocates no buffers.

For example, the call: 

     size_t m_bytes = sizeof(double) * m;
     double* pm;
     size_t n_bytes = sizeof(char) * n;
     char* pn;
     size_t k_bytes = sizeof(struct my_object) * k;
     struct my_object* pk;

     int err = oski_MultiMalloc( file, line, 3,
                  m_bytes, &pm, n_bytes, &pn, k_bytes, &pk );
allocates an array of 'm' doubles, 'n' characters, and 'k' objects. The value 'err' is 0 on success, and 1 on error. Note that the array sizes must be of type 'size_t'.

int oski_ReallocInternal (  void **  p_old_block,
const char *  elem_type,
size_t  elem_size,
size_t  num_elems,
const char *  source_file,
unsigned long  line_number
) 
 

Reallocate a block of memory, and call the error handler on error.

Parameters:
[in,out] p_old_block Pointer to an existing allocated block.
[in] elem_type Type of each logical element stored in the block.
[in] elem_size Size of each logical element, in bytes.
[in] num_elems New no. of elems to store in this block.
[in] source_file Logical source file of the caller (for debugging).
[in] line_number Logical line number of the realloc call (for debugging).
Returns:
0 on success, or a negative error code otherwise.
This routine is for the library's internal use only and should not normally be called directly by users of the library.

Todo:
Implement oski_ReallocInternal().

oski_freefunc_t oski_SetFree (  const oski_freefunc_t  new_func  ) 
 

Change the function used to free allocated memory.

Parameters:
new_func New 'free'-compatible function.
Returns:
Previous function used to allocate memory.
If new_func == NULL, then the memory allocation function is restored to the default, the C 'free' routine.

Postcondition:
If new_func == NULL, then gfuncp_oski_Free == new_func else gfuncp_oski_Free == new_func.

oski_mallocfunc_t oski_SetMalloc (  const oski_mallocfunc_t  new_func  ) 
 

Change the current memory allocation function.

Parameters:
new_func New 'malloc'-compatible function.
Returns:
Previous function used to allocate memory.
If new_func == NULL, then the memory allocation function is restored to the default, the C 'malloc' routine.

Postcondition:
If new_func == NULL, then gfuncp_oski_Malloc == new_func else gfuncp_oski_Malloc == new_func.

oski_reallocfunc_t oski_SetRealloc (  const oski_reallocfunc_t  new_func  ) 
 

Change the current memory re-allocation function.

Parameters:
new_func New 'realloc'-compatible function.
Returns:
Previous function used to allocate memory.
If new_func == NULL, then the memory allocation function is restored to the default, the C 'realloc' routine.

Postcondition:
If new_func == NULL, then gfuncp_oski_Realloc == new_func else gfuncp_oski_Realloc == new_func.

void oski_ZeroMem (  void *  buf,
size_t  num_bytes
) 
 

Zero out bytes in a buffer.

Parameters:
[in,out] buf Buffer to zero out.
[in] num_bytes Number of bytes to clear.

Generated on Wed Sep 19 16:41:22 2007 for BeBOP Optimized Sparse Kernel Interface Library by  doxygen 1.4.6