BeBOP Optimized Sparse Kernel Interface Library  1.0.1h
Defines | Typedefs | Functions
malloc.h File Reference

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

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.

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.


Define Documentation

oski/malloc.h has been included.

#define oski_Free (   ptr)    oski_FreeInternal( ptr )

Customized macro for memory release.

Parameters:
ptrAddress 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).

Referenced by AllocateBlocks(), array_Destroy(), BCSR_GetKernel(), CalcMinMaxMedian(), ConvertFromCSR(), ConvertFullBlocksFromCSR(), ConvertLuaMat(), ConvertSubmatFromCSR(), ConvertToCSR(), CopyPointers(), DefaultMatPowMult(), DestroySubmat(), EstimateBlockCounts(), EstimateFillFromCSC(), EstimateFillFromCSR(), expand_rawmat_csr(), GCLuaMat(), GenTriMat(), main(), MatTransMatMultDefault(), MBCSR_GetSubmatKernel(), oski_CheckHasUniqueInds(), oski_ConvertMatReprToCSR(), oski_CopyMatRepr(), oski_CreateMatCSC_va(), oski_CreateMatCSR_va(), oski_CreateMatReprFromCSR(), oski_DestroyBCSRFillProfile(), oski_DestroyMatRepr(), oski_DestroyMatStruct(), oski_DestroyTimer(), oski_DestroyTrace(), oski_DestroyVecView(), oski_EstimateFillBCSR(), oski_ExpandCSRToFull(), oski_FreeAll(), oski_HeurApplyResults(), oski_HeurEvaluate(), oski_PermuteVecView(), oski_RecordCalls(), oski_RegisterMatType(), oski_ReplaceTunedMatRepr(), oski_ResetStructHintBlocksizes(), oski_ResetStructHintDiaglens(), oski_SortIndices(), oski_StringPrintf(), oski_TransposeCSR(), oski_UnloadProfileMBCSRMatMult(), oski_UnloadProfileMBCSRSymmMatMult(), readhb_pattern(), readhb_pattern_matrix_nnz(), run_read_write_test_battery(), simplelist_Destroy(), testmat_GenBlockedBandedCSR(), testmat_GenRandomCSR(), testmat_GenTriCSR(), and TransposeFullCSR().

#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_typeType of the element to allocate.
[in]num_elemsNumber 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.

Referenced by AllocateBlocks(), array_Duplicate(), CalcMinMaxMedian(), ConvertFromCSR(), ConvertFullBlocksFromCSR(), ConvertSubmatFromCSR(), CopyPointers(), create_rawmat_csr(), CreateMultiVecView_NoError(), DefaultMatPowMult(), EstimateBlockCounts(), EstimateFillFromCSC(), EstimateFillFromCSR(), expand_rawmat_csr(), keropts_Process(), MakeLuaConvMethodName(), MatTransMatMultDefault(), oski_AllocStructHintBlocksizes(), oski_AllocStructHintDiaglens(), oski_ConvertMatReprToCSR(), oski_CopyMatRepr(), oski_CreateMatCSC_va(), oski_CreateMatCSR_va(), oski_CreateMatReprFromCSR(), oski_CreateMatStruct(), oski_CreateTimer(), oski_DuplicateString(), oski_EstimateFillBCSR(), oski_ExpandCSRToFull(), oski_HeurEvaluate(), oski_PermuteVecView(), oski_RecordCalls(), oski_RegisterHeur(), oski_RegisterMatType(), oski_SortIndices(), oski_StringPrintf(), oski_TransposeCSR(), oski_WrapCSC(), oski_WrapCSR(), readhb_pattern(), readhb_pattern_matrix_nnz(), run_read_write_test_battery(), simplelist_Append(), simplelist_Create(), testmat_GenDenseCSR(), testmat_GenTriCSR(), and TransposeFullCSR().

#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.

Referenced by oski_CheckHasUniqueInds().

#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_addrAddress of a pointer to an allocated block.
[in]elem_typeType of each element in the block.
[in]num_elemsSize 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]ptrPointer 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.

References oski_FreeInternal().

Referenced by oski_FreeInternal().

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_typeName of the type of element being allocated (descriptive string).
[in]elem_sizeSize of each element, in bytes.
[in]num_elemsNumber of such elements to allocate.
[in]source_fileSource file of the caller (for debugging).
[in]line_numberLine 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.

References ERR_OUT_OF_MEMORY, oski_HandleError, oski_MallocInternal(), and oski_ZeroMem().

Referenced by oski_MallocInternal().

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

Performs multiple memory allocations.

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'.

References ERR_BAD_ARG, OSKI_ERR, and oski_MultiMalloc().

Referenced by ChooseFastest(), ConvertFullBlocksFromCSR(), ConvertToCSR(), ConvertToCSR_Sorted(), oski_ConvertMatReprToCSR(), oski_CopyMatRepr(), oski_MultiMalloc(), testmat_GenBlockedBandedCSR(), and TransposeFullCSR().

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_blockPointer to an existing allocated block.
[in]elem_typeType of each logical element stored in the block.
[in]elem_sizeSize of each logical element, in bytes.
[in]num_elemsNew no. of elems to store in this block.
[in]source_fileLogical source file of the caller (for debugging).
[in]line_numberLogical 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().

References ERR_OUT_OF_MEMORY, oski_HandleError, and oski_ReallocInternal().

Referenced by oski_ReallocInternal().

Change the function used to free allocated memory.

Parameters:
new_funcNew '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.

References oski_GetFree(), and oski_SetFree().

Referenced by oski_SetFree().

Change the current memory allocation function.

Parameters:
new_funcNew '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.

References oski_GetMalloc(), and oski_SetMalloc().

Referenced by oski_SetMalloc().

Change the current memory re-allocation function.

Parameters:
new_funcNew '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.

References oski_GetRealloc(), and oski_SetRealloc().

Referenced by oski_SetRealloc().

void oski_ZeroMem ( void *  buf,
size_t  num_bytes 
)