apiht.h

用c/c++实现的一个CMPP API

/*---------------------------------------------------------------*
 * File: apiht.h                                     
 * Desc: 实现内存哈希表的定义
 *   
 *                  copyright@Wenyz Aspire Co.
 *                  2002/11/09      
 *-------------------------changeLog ----------------------------*
 * DATE     Author      Description
 *      
 *2002/11/09    wenyz       Created
 *---------------------------------------------------------------
 *2002/11/09    wenyz   整理代码，用于货架技术
 *2002/11/26    wenyz   ANSIC 版本
 *---------------------------------------------------------------*/
 
#ifndef HASH_TABLE_HPP
#define HASH_TABLE_HPP

#include "os.h"


#define SHMHT_OK        0   /*  返回成功 */
#define SHMHT_FAILED    -1  /*  失败  */
#define SHMHT_NOSPACE   -3  /*  没有空间 */
#define SHMHT_NOFOUND   -3  /*  没有该内容包 */


/*
*一个包的内容
*包括 下一个指针，key值，包内容
*/
struct tagrecHashCell
{
    struct  tagrecHashCell* pNext;      /*下一个结点*/
    struct  tagrecHashCell* pPrev;      /*前一个结点*/
    time_t  tMsgTime;                   /*消息操作时间*/
    int     nKeySize;                   /*key的长度*/
    void*   pvKey;                      /*key的内容地址*/
    int     nPckSize;                       /*包体长度*/
    void*   pvPck;                      /*包体内容地址*/
};
typedef struct  tagrecHashCell  recHashCell;

/*
*内存的管理在这个队列实现， 
*申请空间从这个队列读一个包，
*释放空间往这个队列写一个包
*在初始化时候往这个对列写入最多的包
*/
typedef struct tagrecFreeQCell
{
    int nHead;              /*内存管理队列的头*/
    int nTail;              /*内存管理队列的尾*/
    recHashCell**   pvAddr;         /* 地址空间数组 */
}recFreeQCell;  


typedef struct  tagHTCell
{
    int nInitFlag;  /*是否初始化标志*/
    int nShmSize;   /*申请的总共内容包内存大小*/
    int nMsgMaxNum; /*哈希表中包最多个数*/
    int nBucket;    /*哈希表的桶数*/
    int nSize;      /*哈希表中包长度*/
    int nKeySize;   /*哈希表中key的长度*/
            

    int     nIterFlag ;     /* for iterator */
    recHashCell*    pMarkCell;  /* for iterator */
    recHashCell*    pCurrCell;  /* for iterator */
    int nCurrentBucket;     /* for iterator */
    
    void*   pSAddr;     /*内容包的开始地址*/
    void*   pEAddr;     /*内容包的结束地址*/
    time_t  tMsgTime;   /*哈希表中最后一条操作消息时间*/
    pid_t   nMsgPid;    /*哈希表最后一条操作消息进程ID*/
    
    recHashCell** pBucket;  /*哈希表的桶的首指针数组*/  
    recFreeQCell    RecFreeQ;   /*空闲的内存管理队列*/
}recHTCell;

                                                
/*
*function 调试工具
*/
void    vDumpHTApi( FILE* fp, void* pAddr );

/*
描述： 得到HASH表内存的负载系数和包的个数
输入：  pvHLink HT表句柄， 
输出： pnCellNum 包的个数
返回： 0-100负载的百分比系数
*/
int     nGetHTLoadApi( void* pvHTLink, int* pnCellNum );
        
/*
描述： 得到HASH表内存的pBucket指针数组的首地址
输入：  pvHLink HT表句柄， 
输出：  recHashCell*** pppBucket, int* pnCount 指针数组个数
返回： SHMHT_OK 成功
       SHMHT_FAILED 错误，
    
*/
int     nGetHTpBucketApi( void* pvHTLink, recHashCell*** pppBucket, int* pnCount );

/*
描述： 通过KEY得到HASH表内存的pBucket指针的首地址
输入：  pvHLink HT表句柄， pvKeyAddr, KEY的地址， nKeySize  KEY的长度 
输出：  recHashCell** ppBucket
返回： SHMHT_OK 成功
       SHMHT_FAILED 错误，

*/
int     nGetHTpBucketByKeyApi( void* pvHTLink, void* pvKeyAddr, 
                            int nKeySize, recHashCell** ppBucket 
                            );

/*
*描述： 添加一条记录进入HASH表内存
*输入： pHLink HT表句柄， pvKeyAddr KEY值指针， nKeySize KEY长度，
                    pvCellAddr 要添加的包指针，nCellSize 包的长度。 
*输出： SHMHT_OK 成功 ， SHMHT_FAILED 失败 SHMHT_NOSPACE   没有空间
*/
int     nAddACellApi( void* pvHTLink, void* pvKeyAddr, int nKeySize, 
                            void* pvCellAddr, int nCellSize );

/*
*描述： 添加一条记录进入HASH表内存,
                   如果已经有一条的话，就update,如果没有就添加
*输入： pHLink HT表句柄， pvKeyAddr KEY值指针， nKeySize KEY长度，
                   pvCellAddr 要添加的包指针，nCellSize 包的长度。 
*输出： SHMHT_OK, 成功， SHMHT_FAILED 失败  SHMHT_NOSPACE  空间不够
*/
int     nAddACellAndUpdateApi( void* pvHTLink, void* pvKeyAddr, 
                            int nKeySize, void* pvCellAddr, int nCellSize );

/*
描述：删除HASH表内存一条记录
输入：pHLink HT表句柄，pvKeyAddr KEY值指针， nKeySize KEY长度，
nCellSize 包的长度。 
输出：pvCellAddr 删除的包指针
*返回：SHMHT_OK, 成功， SHMHT_FAILED 失败  SHMHT_NOFOUND 没有该包，
*/
int     nDelACellApi( void* pvHTLink, void* pvKeyAddr, int nKeySize, 
                          void* pvCellAddr, int nCellSize );

/*
*描述：查找HASH表内存一条记录
*输入：pHLink HT表句柄，pvKeyAddr KEY值指针， nKeySize KEY长度，
        nCellSize 包的长度。 
*输出：pvCellAddr 查找的包指针
*返回：SHMHT_OK, 成功， SHMHT_FAILED 失败  SHMHT_NOFOUND 没有该包，
*/
int     nSerACellApi( void* pvHTLink, void* pvKeyAddr, int nKeySize, 
                           void* pvCellAddr, int nCellSize );

/*
*描述：更新HASH表内存一条记录
*输入：pHLink HT表句柄，pvKeyAddr KEY值指针， nKeySize KEY长度，
        pvCellAddr 更新的包指针,nCellSize 包的长度。 
*输出： 无
*返回：SHMHT_OK, 成功， SHMHT_FAILED 失败  SHMHT_NOFOUND 没有该包，
*/
int     nUpdateACellApi( void* pvHTLink, void* pvKeyAddr, 
                      int nKeySize, void* pvCellAddr, 
                      int nCellSize );

/*
*描述：通过函数指针更新HASH表一条记录
*输入：pHLink HT表句柄，pvKeyAddr KEY值指针， nKeySize KEY长度，
       int (*pfnPckFunc)( void*, size_t )更新函数的函数指针 void* 为包指针，
       size_t为包的长度
       注意 pfnPckFunc（）为外部使用的更改内存内容的函数，
       可以任意修改内存中数据
*输出： 无
*返回：SHMHT_OK, 成功， SHMHT_FAILED 失败  SHMHT_NOFOUND 没有该包，
*/
int     nUpdateACellByFunc( void* pvHTLink, void* pvKeyAddr, int nKeySize,
                        int (*pfnPckFunc)( void*, size_t ) );

/*
*描述：通过函数指针更新HASH表一条记录, 
*                如果没有该KEY的包，添加进去
*输入：pHLink HT表句柄，pvKeyAddr KEY值指针， nKeySize KEY长度，
       int (*pfnPckFunc)( void*, size_t )更新函数的函数指针 void* 为包指针，
       size_t为包的长度
       注意 pfnPckFunc（）为外部使用的更改内存内容的函数，
                    可以任意修改内存中数据
*输出： 无
*返回：SHMHT_OK, 成功， SHMHT_FAILED 失败  SHMHT_NOSPACE 没有内存空间
*/
int     nAddOrUpdateACellByFunc( void* pvHTLink, void* pvKeyAddr, int nKeySize, 
                                 void* pvCellAddr, int nCellSize,
                                 int (*pfnPckFunc)( void*, size_t ) );

/*
*描述： 取出一个超时的记录
*输入： pHLink HT表句柄， nTimeOut 超过时间间隔
*输出pvKeyAddr KEY值指针， nKeySize KEY长度，
    pvCellAddr 查找的包指针，nCellSize 包的长度。 
*返回：>=0 成功 ， <0 失败
*/
int     nGetTimeOutACellApi( void* pHTLink, int    nTimeOut, void* pvKeyAddr, 
                          int nKeySize, void* pvCellAddr, int nCellSize );

/*
*描述： 删除HASH表内存一条记录（通过包内容）
*输入： pHLink HT表句柄
    pvCellAddr 删除的包指针，nCellSize 包的长度。 
*输出： pvKeyAddr KEY值指针， nKeySize KEY长度
*返回： SHMHT_OK 成功
        SHMHT_FAILED 错误，
*/
int     nDelACellByPckApi( void* pvHTLink, void* pvKeyAddr, 
                        int nKeySize, void* pvCellAddr, 
                        int nCellSize );

/*
描述： 复位HASH表内存
输入：  pvHLink HT表句柄， 
                
输出： 
返回： 0 成功，-1 输入参数错误，-2 内部函数错误
*/
int     nResetShmHTApi( void* pvHLink );


/*--------------------------*
 *内存表的三个函数定义      *   
 ---------------------------*/

/*
描述： 初始化固定长度的HASH表内存
输入：  nKeySize KEY值的长度。 nPckSize 包体长度
    nBucket 桶的个数, nPckCount 包的个数        
*返回：HT表句柄 >0 成功 ， NULL 失败
*/
void*   pvInitMemHT( int nKeySize, int nPckSize, int nBucket, int nPckCount );


/*
*描述： 释放该HASH表的内存
*输入：  pvHLink HT表句柄
*输出： 无 
返回： SHMHT_OK 成功，SHMHT_FAILED 错误
*/
int     nRemoveMemHT(  void* pvHLink );

/*
*描述： 复位HASH表内存
*输入：  pvHLink HT表句柄， 
                
*输出： 
*返回： SHMHT_OK 成功，SHMHT_FAILED 错误
*/
int     nResetMemHT( void* pvHLink );



/*
*描述： 检查输入参数合法性
*输入： pHLink HT表句柄
    nKeySize KEY 长度 nCellSize 包的长度。 
*输出： 
*返回： SHMHT_OK 成功
       SHMHT_FAILED 错误，
*/
int     nCheckInputSize( int nKeySize, int nCellSize, const recHTCell* pHTLink );

/*
*描述： 从一个桶中取出一个超时的记录
*输入： pHLink HT表句柄，nBucket 桶的下标， nTimeOut 超过时间间隔
    输出pvKeyAddr KEY值指针， nKeySize KEY长度，
    pvCellAddr 查找的包指针，nCellSize 包的长度。
    如果pvKeyAddr, nKeySize , pvCellAddr, nCellSize 为空的话，
  清除所有超时的包 
    *输出：>=0 成功 清除的包的个数， SHMHT_FAILED 失败 
*/
int    nGetABucketTimeOutCell( void* pvHTLink, int nBucket, 
                               int nTimeOut,  void* pvKeyAddr, 
                               int nKeySize, void* pvCellAddr, 
                               int nCellSize );

#endif