ACL缓存开发

　　在编写高效的程序时，内存缓存有时是非常有用的，提到缓存，大家可能会很容易想到可以使用哈希表这种最常用的方式来缓存内存对象，但哈希的实现代码一般不具备两项功能：缓存过期时间、缓存数量限制，如果要增加对此二项功能的支持，一般需要增加辅助的链表结构。如果使用ACL里的 ACL_CACHE，则在高效缓存的前提下支持这两项功能。

　　下面是ACL_CACHE的数据结构及常用的接口调用：

一、数据结构及常用接口说明

 

1、数据结构定义

/**
 * 缓冲池对象结构定义
 */
typedef struct ACL_CACHE { 
	ACL_HTABLE *table;	/**< 哈希表 */
	ACL_RING ring;		/**< 将被删除的对象的数据链表 */
	int   max_size;                 /**< 缓存池容量大小限制值 */
	int   size;		                /**< 当前缓存池中的缓存对象个数 */
	int   timeout;		        /**< 每个缓存对象的生存时长(秒) */

	/**< 释放用户动态对象的释放回调函数 */
	void  (*free_fn)(const ACL_CACHE_INFO*, void *);
	acl_pthread_mutex_t lock;	/**< 缓存池锁 */
	ACL_SLICE *slice;		/**< 内存切片对象 */

	/* for acl_iterator */

	/* 取迭代器头函数 */
	const void *(*iter_head)(ACL_ITER*, struct ACL_CACHE*);
	/* 取迭代器下一个函数 */
	const void *(*iter_next)(ACL_ITER*, struct ACL_CACHE*);
	/* 取迭代器尾函数 */
	const void *(*iter_tail)(ACL_ITER*, struct ACL_CACHE*);
	/* 取迭代器上一个函数 */
	const void *(*iter_prev)(ACL_ITER*, struct ACL_CACHE*);
	/* 取迭代器关联的当前容器成员结构对象 */
	const ACL_CACHE_INFO *(*iter_info)(ACL_ITER*, struct ACL_CACHE*);
} ACL_CACHE;

/**
 * 缓存池中存储的缓存对象
 */
typedef struct ACL_CACHE_INFO {
	char *key;		/**< 健值 */
	void *value;		/**< 用户动态对象 */
	int   nrefer;		/**< 引用计数 */
	time_t when_timeout;	/**< 过期时间截 */
	ACL_RING entry;		/**< 内部数据链成员 */
} ACL_CACHE_INFO;

 

2、创建与释放接口

/**
 * 创建一个缓存池，并设置每个缓存对象的最大缓存时长及该缓存池的空间容量限制
 * @param max_size {int} 该缓存池的容量限制
 * @param timeout {int} 每个缓存对象的缓存时长
 * @param free_fn {void (*)(void*)} 用户级的释放缓存对象的函数
 * @return {ACL_CACHE*} 缓存池对象句柄
 */
ACL_API ACL_CACHE *acl_cache_create(int max_size, int timeout,
	void (*free_fn)(const ACL_CACHE_INFO*, void*));

/**
 * 释放一个缓存池，并自动调用 acl_cache_create()/3 中的释放函数释放缓存对象
 * @param cache {ACL_CACHE*} 缓存池对象句柄
 */
ACL_API void acl_cache_free(ACL_CACHE *cache);

 

3、增、删、查接口

/**
 * 向缓存池中添加被缓存的对象
 * @param cache {ACL_CACHE*} 缓存池对象句柄
 * @param key {const char*} 缓存对象的健值
 * @param value {void*} 动态缓存对象
 * @return {ACL_CACHE_INFO*} 缓存对象所依附的结构对象，其中的 value 与用户的对象相同,
 *   如果返回 NULL 则表示添加失败，失败原因为：缓存池太大溢出或相同健值的对象存在
 *   且引用计数非0; 如果返回非 NULL 则表示添加成功，如果对同一健值的重复添加，会用
 *   新的数据替换旧的数据，且旧数据调用释放函数进行释放
 */
ACL_API ACL_CACHE_INFO *acl_cache_enter(ACL_CACHE *cache, const char *key, void *value);

/**
 * 从缓存池中查找某个被缓存的对象
 * @param cache {ACL_CACHE*} 缓存池对象句柄
 * @param key {const char*} 查询健
 * @return {void*} 被缓存的用户对象的地址，为NULL时表示未找到
 */
ACL_API void *acl_cache_find(ACL_CACHE *cache, const char *key);

/**
 * 从缓存池中查找某个被缓存的对象所依附的缓存信息对象
 * @param cache {ACL_CACHE*} 缓存池对象句柄
 * @param key {const char*} 查询健
 * @return {ACL_CACHE_INFO*} 缓存信息对象地址，为NULL时表示未找到
 */

/**
 * 从缓存池中删除某个缓存对象
 * @param cache {ACL_CACHE*} 缓存池对象句柄
 * @param key {const char*} 健值
 * @return {int} 0: 表示删除成功; -1: 表示该对象的引用计数非0或该对象不存在
 */
ACL_API int acl_cache_delete2(ACL_CACHE *cache, const char *key);

 

4、同步互斥接口

/**
 * 加锁缓存池对象，在多线程时用
 * @param cache {ACL_CACHE*} 缓存池对象句柄
 */
ACL_API void acl_cache_lock(ACL_CACHE *cache);

/**
 * 解锁缓存池对象，在多线程时用
 * @param cache {ACL_CACHE*} 缓存池对象句柄
 */
ACL_API void acl_cache_unlock(ACL_CACHE *cache);

 

5、遍历接口

/**
 * 遍历缓存中的所有对象
 * @param cache {ACL_CACHE*} 缓存池对象句柄
 * @param walk_fn {void (*)(ACL_CACHE_INFO*, void*)} 遍历回调函数
 * @param arg {void *} walk_fn()/2 中的第二个参数
 */
ACL_API void acl_cache_walk(ACL_CACHE *cache, void (*walk_fn)(ACL_CACHE_INFO *, void *), void *arg);

 　当然，因为 ACL_CACHE 符合 ACL_ITER 通用迭代器(C语言中迭代器的设计与使用 )的规则要求，所以也可以采用ACL通用迭代方式遍历ACL_CACHE内部缓存对象，如下：

 typedef struct {
  char  name[32];
  char  dummy[32];
} MY_DAT;

static free_mydat_fn(const ACL_CACHE_INFO *info, void *arg)
{
  MY_DAT *mydat = (MY_DAT*) mydat;

  acl_myfree(mydat);
}

void test(void)
{
  ACL_CACHE *cache;
  ACL_ITER iter;
  MY_DAT *mydat;
  char  key[32];

  /* 创建缓存对象句柄 */
  cache = acl_cache_create(100, 60, free_mydat_fn);

  /* 向缓存中添加缓存数据 */
  for (i = 0; i < 10; i++) {
    mydat = (MY_DAT*) acl_mymalloc(sizeof(MY_DAT));
    snprintf(key, sizeof(key), "key:%d", i);
    snprintf(mydat->name, sizeof(mydat->name), "name: %d", i);
    (void) acl_cache_enter(cache, key, mydat);
  }

  /* 遍历所有缓存数据 */
  acl_foreach(iter, cache) {
    const MY_DAT *mydat = (const MY_DAT*) iter.data;
    printf(">>>name: %s\n", mydat->name);
  }

  /* 释放缓存句柄并清除缓存数据 */
   acl_cache_free(cache);
}

 

　除了以上几个常用接口外，ACL_CACHE　模块还提供了其它方便使用的接口调用方式，参见: lib_acl/include/stdlib/acl_cache.h 头文件说明。

 

二、举例

　下面是一个完整使用 ACL_CACHE 的例子：

#include "lib_acl.h"
#include <stdio.h>
#include <stdlib.h>
#include <assert.h>

/* 用户自定义数据结构 */
typedef struct {
	char *buf;
	int   len;
} MYOBJ;

/**
 * 释放用户数据回调数据
 * @param info {const ACL_CACHE_INFO*} 用户缓存数据所依附的ACL_CACHE 的某个数据对象
 * @param arg {void*} 用户数据对象以 void * 表示
 */
static void free_fn(const ACL_CACHE_INFO *info, void *arg)
{
	MYOBJ *o = (MYOBJ*) arg;

	printf("%s: when_timeout: %ld, now: %ld, len: %d, deleted\n",
		info->key, (long) info->when_timeout, (long) time(NULL), o->len);

	acl_myfree(o->buf);
	acl_myfree(o);
}

/**
 * 创建一个新的用户数据对象
 * @param len {int} MYOBJ.buf 的长度
 * @return {MYOBJ*}
static MYOBJ *myobj_new(int len)
{
	MYOBJ *o = (MYOBJ*) acl_mymalloc(sizeof(MYOBJ));

	o->buf = (char*) acl_mymalloc(len <= 0 ? 100 : len);
	o->len = len;
	return (o);
}

/**
 * 遍历数据数据缓存中每一个数据对象的回调函数
 * @param info {ACL_CACHE_INFO*}
 * @arg {void*} 用户数据对象
 */
static void walk_fn(ACL_CACHE_INFO *info, void *arg)
{
	MYOBJ *o = (MYOBJ*) info->value;

       assert(info->value == arg);
	printf("%s: size: %d; when_timeout: %ld\n", info->key, o->len, (long) info->when_timeout);
}

static void usage(const char *procname)
{
	printf("usage: %s -h [help] -n max_size -t timeout\n", procname);
}

int main(int argc, char *argv[])
{
	int   i, n = 100, ch, timeout = 1;
	ACL_CACHE_INFO *info;
	ACL_CACHE *cache;
	char  key[32];
	MYOBJ *o;

	while ((ch = getopt(argc, argv, "hn:t:")) > 0) {
		switch (ch) {
			case 'h':
				usage(argv[0]);
				exit (0);
			case 'n':
				n = atoi(optarg);
				break;
			case 't':
				timeout = atoi(optarg);
				break;
			default:
				break;
		}
	}
	
        /* 创建缓存句柄 */
	cache = acl_cache_create(n, timeout, free_fn);

        /* 向缓存中添加用户缓存数据 */
	for (i = 0; i < n + 5; i++) {
		o = myobj_new(i + 1);
		snprintf(key, sizeof(key), "key(%d)", i);
		assert(acl_cache_enter(cache, key, o));
		printf("add one: %s\n", key);
		sleep(1);
	}

	printf("\nfirst walk cache, cache size: %d\n", acl_cache_size(cache));

	/* 遍历所有缓存数据 */
	acl_cache_walk(cache, walk_fn, NULL);
	printf("\nfirst call acl_cache_timeout, size: %d\n", acl_cache_size(cache));

	/* 过期的缓存数据被自动删除 */
	acl_cache_timeout(cache);
	printf(">>>after first acl_cache_timeout, second walk cache, cache's size: %d\n", acl_cache_size(cache));

	/* 遍历所有缓存数据 */
	acl_cache_walk(cache, walk_fn, NULL);

	printf("\n");
	i = 0;

	/* 休眠以使有些缓存数据过期 */
	while (i++ < 5) {
		printf("slee one second, i=%d\n", i);
		sleep(1);
	}

	printf("\nsecond call acl_cache_timeout, size: %d\n", acl_cache_size(cache));

	/* 过期的缓存数据被自动删除 */
	acl_cache_timeout(cache);
	printf(">>>after second acl_cache_timeout, third walk_cache, cache's size: %d\n", acl_cache_size(cache));

	/* 遍历所有缓存数据 */
	acl_cache_walk(cache, walk_fn, NULL);

	/* 查询缓存对象 */
	o = (MYOBJ*) acl_cache_find(cache, "key(5)");
	if (o == NULL)
		printf("\n>>>key(5) not exist\n");
	else
		printf("\n>>>key(5): len: %d\n", o->len);

	/* 定位用户缓存数据所依附的缓存对象 */
	info = acl_cache_locate(cache, "key(11)");
	if (info == NULL)
		printf("\n>>>key(11) not exist\n");
	else {
		o = (MYOBJ*) info->value;
		printf("\n>>>key(11): len: %d, when_timeout: %ld\n", o->len, (long) info->when_timeout);
	}

	printf("\nfree cache, size: %d\n", acl_cache_size(cache));

	/* 释放缓存并清除所有用户缓存数据 */
	acl_cache_free(cache);
	return (0);
}

ACL　库下载位置：http://acl.sourceforge.net/

个人微博：http://weibo.com/zsxxsz