/************************************************************************
 *
 *	Copyright (C) 2003-2004
 *	Shenzhen SCADA Control Technology Co., Ltd.
 *	All rights reserved.
 *	
 *	用于调试内存泄漏的对内存分配函数
 *
 *	创建日期:	2005/04/12
 *
 ***********************************************************************/

#ifndef __OS_HEAP_H_ASDFJLCXJVZXHCROEYUIODFGFMHFOIUHSDIHFZXKJCHGVLSDHFAJD
#define __OS_HEAP_H_ASDFJLCXJVZXHCROEYUIODFGFMHFOIUHSDIHFZXKJCHGVLSDHFAJD

#include "basetype.h"

/*!
 *  \brief 堆内存分配
 *
 *  \param size 希望分配的内存的尺寸
 *  \param file 指向发生堆内存分配的源代码文件名称，以null字符结尾。
 *              如果等于NULL， 表示匿名源代码文件名(anony)
 *  \param line 发生堆内存分配的源代码行号
 *
 *  \retutrn 
 *      对内存分配成功的情况下，返回指向分配的内存的指针。如果内存
 *      分配失败，返回NULL。
 *
 *  \note
 *      当分配的内存不在使用时，必须调用heap_free是否分配的内存。
 *
 *      参见 ANSI C 函数 malloc。
 */
DSLIB_API void * heap_malloc (size_t size, const char * file, int line);


/*!
 *  \brief 堆内存分配, 且内存块被初始化0.
 *
 *  \param num      内存块个数
 *  \param elm_size 每一个内存块的尺寸(字节)
 *  \param file 指向发生堆内存分配的源代码文件名称，以null字符结尾。
 *              如果等于NULL， 表示匿名源代码文件名(anony)
 *  \param line 发生堆内存分配的源代码行号
 *
 *  \retutrn 
 *      对内存分配成功的情况下，返回指向分配的内存的指针。如果内存
 *      分配失败，返回NULL。
 *
 *  \note
 *      当分配的内存不在使用时，必须调用heap_free释放分配的内存。
 *      
 *      参见 ANSI C 函数 calloc。本函数与 calloc 不同之处在于不能
 *      象calloc那样保证返回的堆内存块的其实地址对齐在elm_size边界
 *      上。
 */
DSLIB_API void * heap_calloc (size_t num, size_t elm_size, 
                    const char * file, int line);

/*!
 *  \brief  释放堆内存
 *
 *  \param  mb  指向先前调用heap_alloc/heap_calloc分配的内存。
 *
 *  \return 
 *      无。
 */
DSLIB_API void heap_free (void * mb);

/*!
 *  \brief  报告堆内存分配
 *
 *  调用本函数将堆内存分配情况以追加的方式输出到指定文件中。
 *
 *  \param fname 对内存分配报告将输出到该文件中。如果fname等于NULL，
 *              则报告将输出到标准输出上。
 *
 *  \retval -1 函数调用失败。
 *  \retval 0  函数调用成功。
 */
DSLIB_API int heap_report (const char * fname);

/*
 *  堆内存分配和释放宏定义, 为了方便使用者而提供这些宏定义。
 *
 *  1. HEAP_MALLOC(_size)
 *  2. HEAP_CALLOC(_num, _elm_size)
 *  3. HEAP_FREE(_mb)
 */
#define HEAP_MALLOC(_size)  heap_malloc((_size), __FILE__, __LINE__)

#define HEAP_CALLOC(_num, _elm_size)    heap_calloc((_num), (_elm_size), __FILE__, __LINE__)

#define HEAP_FREE(_mb) do{if(_mb) {heap_free((_mb)); (_mb) = NULL;}} while(0)

#ifdef DISABLE_OS_HEAP
  #undef HEAP_MALLOC
  #undef HEAP_CALLOC
  #undef HEAP_FREE

  #define HEAP_MALLOC(_size)            malloc(_size)
  
  #define HEAP_CALLOC(_num, _elm_size)  calloc(_num, _elm_size)
  
  #define HEAP_FREE(_mb) do {if (_mb) {free(_mb); (_mb) = NULL;}} while(0)

#endif

#endif /* __OS_HEAP_H_ASDFJLCXJVZXHCROEYUIODFGFMHFOIUHSDIHFZXKJCHGVLSDHFAJD */