zdb.h 文件参考

#include "../stdlib/acl_define.h"
#include "../stdlib/acl_vstring.h"
#include "../stdlib/acl_fhandle.h"

zdb.h 的引用(Include)关系图:

浏览源代码.

类
struct	ZDB_DISK
struct	ZDB_CFG
struct	ZDB
struct	ZDB_DAT_HDR
struct	ZDB_KEY_HDR
struct	ZDB_BLK_HDR
struct	ZDB_BLK_OFF
struct	ZDB_BLK
struct	ZDB_STORE
struct	ZDB_KEY_STORE
struct	ZDB_DAT_STORE

宏定义
#define	ZDB_FLAG_LINK_BUSY   (1 << 0) /* 将值存储中的占用数据块连接起来 */
#define	ZDB_FLAG_OPEN_LOCK   (1 << 1) /* 以加锁模式打开存储句柄 */
#define	ZDB_FLAG_CACHE_DAT   (1 << 2) /* 是否缓存值存储的数据 */
#define	ZDB_FLAG_CACHE_KEY   (1 << 3) /* 是否缓存键存储的数据 */
#define	ZDB_FLAG_SLICE_KEY   (1 << 4) /* 启用值存储时是否采用内存切片方式 */
#define	ZDB_FLAG_SLICE_DAT   (1 << 5) /* 启用键存储时是否采用内存切片方式 */
#define	ZDB_STAT_KEY_NEW   (1 << 0) /* 新键 */
#define	STORE_FLAG_KEY   (1 << 0) /* 表示是键存储 */
#define	STORE_FLAG_DAT   (1 << 1) /* 表示是值存储 */
#define	STORE_FLAG_IO_SLICE   (1 << 2) /* 是否启用 ZDB_IO 的内存切片分配方式 */
#define	zdb_blk_data(b)   ((b)->dat)
#define	zdb_blk_free(b)   acl_myfree((b))

类型定义
typedef struct ZDB	ZDB
typedef struct ZDB_KEY_HDR	ZDB_KEY_HDR
typedef struct ZDB_BLK	ZDB_BLK
typedef struct ZDB_BLK_OFF	ZDB_BLK_OFF
typedef struct ZDB_DAT_HDR	ZDB_DAT_HDR
typedef struct ZDB_KEY_STORE	ZDB_KEY_STORE
typedef struct ZDB_DAT_STORE	ZDB_DAT_STORE
typedef struct ZDB_IO	ZDB_IO
typedef acl_int64	zdb_off_t
typedef acl_int64	zdb_key_t
typedef int	zdb_lnk_t
typedef struct ZDB_DISK	ZDB_DISK
typedef struct ZDB_CFG	ZDB_CFG
typedef struct ZDB_BLK_HDR	ZDB_BLK_HDR
typedef struct ZDB_STORE	ZDB_STORE

函数
ACL_API void	zdb_test (const char *cmd)
ACL_API void	zdb_init (void)
ACL_API void	zdb_end (void)
ACL_API void	zdb_sync (ZDB *db)
ACL_API ZDB *	zdb_open (const char *dbname, unsigned int oflags, const ZDB_CFG *cfg)
ACL_API void	zdb_close (ZDB *db)
ACL_API ZDB_BLK *	zdb_lookup (ZDB *db, zdb_key_t key, size_t *size, ZDB_BLK_OFF *blk_off_buf)
ACL_API int	zdb_update (ZDB *db, zdb_key_t key, const ZDB_BLK_OFF *blk_off_saved, const void *dat, size_t len)
ACL_API int	key_store_header_sync (ZDB_KEY_STORE *store)
ACL_API ZDB_KEY_STORE *	zdb_key_store_open (ZDB *db, zdb_key_t key)
ACL_API ZDB_KEY_STORE *	zdb_key_store_open2 (ZDB *db, const char *filepath)
ACL_API void	zdb_key_store_close (ZDB_KEY_STORE *store)
ACL_API int	zdb_key_set (ZDB *db, zdb_key_t key, const ZDB_BLK_OFF *blk_off)
ACL_API int	zdb_key_get (ZDB *db, zdb_key_t key, ZDB_BLK_OFF *blk_off)
ACL_API int	zdb_key_status (ZDB *db, const char *filepath, ZDB_KEY_HDR *key_hdr)
ACL_API int	zdb_key_check3 (ZDB *db, const char *filepath, ZDB_KEY_HDR *key_hdr)
ACL_API int	zdb_key_check (ZDB_KEY_STORE *store, ZDB_KEY_HDR *key_hdr)
ACL_API int	zdb_key_init (ZDB *db, zdb_key_t key_begin, zdb_key_t key_end)
ACL_API int	dat_store_header_sync (ZDB_DAT_STORE *store)
ACL_API void	zdb_dat_store_close (ZDB_DAT_STORE *store)
ACL_API ZDB_DAT_STORE *	zdb_dat_store_open (ZDB *db, const char *filepath)
ACL_API ZDB_BLK *	zdb_dat_get (ZDB *db, const ZDB_BLK_OFF *blk_off, zdb_key_t *key, size_t *size)
ACL_API int	zdb_dat_add (ZDB *db, zdb_key_t key, const void *dat, int len)
ACL_API int	zdb_dat_update (ZDB *db, zdb_key_t key, const ZDB_BLK_OFF *blk_off, const void *dat, size_t len)
ACL_API int	zdb_dat_stat (ZDB *db, const char *filepath, ZDB_DAT_HDR *dat_hdr)
ACL_API int	zdb_dat_check3 (ZDB *db, const char *filepath, ZDB_DAT_HDR *dat_hdr)
ACL_API int	zdb_dat_check (ZDB_DAT_STORE *store, ZDB_DAT_HDR *dat_hdr)
ACL_API int	zdb_key_walk (ZDB *db, int(*walk_fn)(ZDB_KEY_STORE *store))
ACL_API int	zdb_dat_walk (ZDB *db, int(*walk_fn)(ZDB_DAT_STORE *store))
ACL_API void	zdb_dat_iter_set (ZDB_DAT_STORE *store, int read_data)

宏定义说明

STORE_FLAG_DAT

#define STORE_FLAG_DAT   (1 << 1) /* 表示是值存储 */

在文件 zdb.h 第 217 行定义.

STORE_FLAG_IO_SLICE

#define STORE_FLAG_IO_SLICE   (1 << 2) /* 是否启用 ZDB_IO 的内存切片分配方式 */

在文件 zdb.h 第 218 行定义.

STORE_FLAG_KEY

#define STORE_FLAG_KEY   (1 << 0) /* 表示是键存储 */

在文件 zdb.h 第 216 行定义.

zdb_blk_data

#define zdb_blk_data

(

b

)

((b)->dat)

从 ZDB_BLK 中取得用户数据

参数

b	{ZDB_BLK*}

返回

{void*}

在文件 zdb.h 第 310 行定义.

zdb_blk_free

#define zdb_blk_free

(

b

)

acl_myfree((b))

释放由 zdb_lookup()/3 返回的数据空间

参数

b	{ZDB_BLK*}

在文件 zdb.h 第 316 行定义.

ZDB_FLAG_CACHE_DAT

#define ZDB_FLAG_CACHE_DAT   (1 << 2) /* 是否缓存值存储的数据 */

在文件 zdb.h 第 66 行定义.

ZDB_FLAG_CACHE_KEY

#define ZDB_FLAG_CACHE_KEY   (1 << 3) /* 是否缓存键存储的数据 */

在文件 zdb.h 第 67 行定义.

ZDB_FLAG_LINK_BUSY

#define ZDB_FLAG_LINK_BUSY   (1 << 0) /* 将值存储中的占用数据块连接起来 */

在文件 zdb.h 第 64 行定义.

ZDB_FLAG_OPEN_LOCK

#define ZDB_FLAG_OPEN_LOCK   (1 << 1) /* 以加锁模式打开存储句柄 */

在文件 zdb.h 第 65 行定义.

ZDB_FLAG_SLICE_DAT

#define ZDB_FLAG_SLICE_DAT   (1 << 5) /* 启用键存储时是否采用内存切片方式 */

在文件 zdb.h 第 69 行定义.

ZDB_FLAG_SLICE_KEY

#define ZDB_FLAG_SLICE_KEY   (1 << 4) /* 启用值存储时是否采用内存切片方式 */

在文件 zdb.h 第 68 行定义.

ZDB_STAT_KEY_NEW

#define ZDB_STAT_KEY_NEW   (1 << 0) /* 新键 */

在文件 zdb.h 第 72 行定义.

类型定义说明

ZDB

typedef struct ZDB ZDB

在文件 zdb.h 第 10 行定义.

ZDB_BLK

typedef struct ZDB_BLK ZDB_BLK

在文件 zdb.h 第 12 行定义.

ZDB_BLK_HDR

typedef struct ZDB_BLK_HDR ZDB_BLK_HDR

ZDB_BLK_OFF

typedef struct ZDB_BLK_OFF ZDB_BLK_OFF

在文件 zdb.h 第 13 行定义.

ZDB_CFG

typedef struct ZDB_CFG ZDB_CFG

ZDB_DAT_HDR

typedef struct ZDB_DAT_HDR ZDB_DAT_HDR

在文件 zdb.h 第 14 行定义.

ZDB_DAT_STORE

typedef struct ZDB_DAT_STORE ZDB_DAT_STORE

在文件 zdb.h 第 16 行定义.

ZDB_DISK

typedef struct ZDB_DISK ZDB_DISK

ZDB_IO

typedef struct ZDB_IO ZDB_IO

在文件 zdb.h 第 17 行定义.

ZDB_KEY_HDR

typedef struct ZDB_KEY_HDR ZDB_KEY_HDR

在文件 zdb.h 第 11 行定义.

ZDB_KEY_STORE

typedef struct ZDB_KEY_STORE ZDB_KEY_STORE

在文件 zdb.h 第 15 行定义.

zdb_key_t

typedef acl_int64 zdb_key_t

在文件 zdb.h 第 23 行定义.

zdb_lnk_t

typedef int zdb_lnk_t

在文件 zdb.h 第 26 行定义.

zdb_off_t

typedef acl_int64 zdb_off_t

在文件 zdb.h 第 20 行定义.

ZDB_STORE

typedef struct ZDB_STORE ZDB_STORE

函数说明

dat_store_header_sync()

ACL_API int dat_store_header_sync

(

ZDB_DAT_STORE *

store

)

同步值存储头至磁盘

参数

store

{ZDB_DAT_STORE*} 值存储句柄

返回

{int} -1: error, > 0 ok

key_store_header_sync()

ACL_API int key_store_header_sync

(

ZDB_KEY_STORE *

store

)

同步键存储头至磁盘

参数

store

{ZDB_KEY_STORE*} 值存储句柄

返回

{int} -1: error, > 0 ok

zdb_close()

ACL_API void zdb_close

(

ZDB *

db

)

关闭 ZDB 数据库句柄

参数

db	{ZDB*} ZDB 数据库句柄

zdb_dat_add()

ACL_API int zdb_dat_add	(	ZDB *	db,
		zdb_key_t	key,
		const void *	dat,
		int	len
	)

向值存储中添加新数据

参数

db	{ZDB*}
key	{zdb_key_t} 键值
dat	{const void*} 数据地址
len	{size_t} dat 数据长度

返回

{int} 0: 数据没有更新; 1: 数据更新; -1: 出错

zdb_dat_check()

ACL_API int zdb_dat_check	(	ZDB_DAT_STORE *	store,
		ZDB_DAT_HDR *	dat_hdr
	)

zdb_dat_check3()

ACL_API int zdb_dat_check3	(	ZDB *	db,
		const char *	filepath,
		ZDB_DAT_HDR *	dat_hdr
	)

检查值存储中的数据块的正确性

参数

db	{ZDB*}
filepath	{const char*} 值存储文件名
dat_hdr	{ZDB_DAT_HDR*} 若非空则存储值存储头信息

返回

{int} 0: ok; -1: error

zdb_dat_get()

ACL_API ZDB_BLK* zdb_dat_get	(	ZDB *	db,
		const ZDB_BLK_OFF *	blk_off,
		zdb_key_t *	key,
		size_t *	size
	)

从值存储中取得对应的数据

参数

db	{ZDB*}
blk_off	{const ZDB_BLK_OFF*}
key	{zdb_key_t*} 存储键的值
size	{size_t*} 存储数据的长度

返回

{void*} 数据地址，若找到则不为空，找不到或出错则为空, 若不为空, 则需要用 zdb_blk_free()/1 进行释放 注意: 当 size 指针地址非空时，调用者的类型必须是 size_t 类型而非 int 类型，因为在 64位机上 size_t 为8个字节长度，而 int 为4个字节长度，内部在对 size 地址赋值 时，编译器会自动按 size_t 的真实空间长度赋值，如果调用者的 size 为 int 类型， 则就会出现空间越办现象，从而会使整个程序出现莫名其妙的问题，并且用 valgrind 也查不出这个错误来!

zdb_dat_iter_set()

ACL_API void zdb_dat_iter_set	(	ZDB_DAT_STORE *	store,
		int	read_data
	)

设置值存储的迭代器

参数

store	{ZDB_DAT_STORE*}
read_data	{int} 是否需要读取数据块中的数据部分, !0: 表示读取数据块中的 数据部分; 0: 仅读取数据块中的头

zdb_dat_stat()

ACL_API int zdb_dat_stat	(	ZDB *	db,
		const char *	filepath,
		ZDB_DAT_HDR *	dat_hdr
	)

读取值存储的头信息

参数

db	{ZDB*}
filepath	{const char*} 值存储文件名
dat_hdr	{ZDB_DAT_HDR*} 存储结果 @retur {int} 0: ok; -1: error

zdb_dat_store_close()

ACL_API void zdb_dat_store_close

(

ZDB_DAT_STORE *

store

)

关闭值存储

参数

store

{ZDB_DAT_STORE*} 值存储句柄

zdb_dat_store_open()

ACL_API ZDB_DAT_STORE* zdb_dat_store_open	(	ZDB *	db,
		const char *	filepath
	)

打开或创建值存储

参数

filepath

{const char*} 值存储文件全路径

返回

{ZDB_DAT_STORE*} !NULL: ok; NULL: error

zdb_dat_update()

ACL_API int zdb_dat_update	(	ZDB *	db,
		zdb_key_t	key,
		const ZDB_BLK_OFF *	blk_off,
		const void *	dat,
		size_t	len
	)

更新值存储中的数据信息

参数

db	{ZDB*}
key	{zdb_key_t} 键
blk_off	{const ZDB_BLK_OFF*} 存储于键存储中相应值的位置信息
dat	{const void*} 数据地址
len	{size_t} dat 数据长度

返回

{int} 0: 数据没有更新; 1: 数据更新; -1: 出错

zdb_dat_walk()

ACL_API int zdb_dat_walk	(	ZDB *	db,
		int(*)(ZDB_DAT_STORE *store)	walk_fn
	)

zdb_end()

ACL_API void zdb_end

(

void

)

程序退出前需要释放 zdb 内部一些资源

zdb_init()

ACL_API void zdb_init

(

void

)

程序开始运行时需要初始化 zdb

zdb_key_check()

ACL_API int zdb_key_check	(	ZDB_KEY_STORE *	store,
		ZDB_KEY_HDR *	key_hdr
	)

zdb_key_check3()

ACL_API int zdb_key_check3	(	ZDB *	db,
		const char *	filepath,
		ZDB_KEY_HDR *	key_hdr
	)

遍历键存储中的键的状态

参数

db	{ZDB*}
filepath	{const char*} 键存储文件全路径
key_hdr	{ZDB_KEY_HDR*} 若非空则用来存放键存储头信息的内存地址

返回

{int} 0: ok; -1: error

zdb_key_get()

ACL_API int zdb_key_get	(	ZDB *	db,
		zdb_key_t	key,
		ZDB_BLK_OFF *	blk_off
	)

根据键值从键存储中取得该键所对应的数据索引位置

参数

db	{ZDB*}
key	{zdb_key_t} 键值
blk_off	{ZDB_BLK_OFF*} 存储结果的对象

返回

{int} 1: 表示查到, 0: 表示未查到, -1: 表示出错

zdb_key_init()

ACL_API int zdb_key_init	(	ZDB *	db,
		zdb_key_t	key_begin,
		zdb_key_t	key_end
	)

初始化键存储

参数

db	{ZDB*}
key_begin	{zdb_key_t} 起始键值
key_end	{zdb_key_t} 结束键值

返回

{int} 0: ok; -1: error

zdb_key_set()

ACL_API int zdb_key_set	(	ZDB *	db,
		zdb_key_t	key,
		const ZDB_BLK_OFF *	blk_off
	)

设置键存储中键位置的值位置值

参数

db	{ZDB*}
key	{zdb_key_t}
blk_off	{const ZDB_BLK_OFF*}

返回

{int} 0: ok; -1: error

zdb_key_status()

ACL_API int zdb_key_status	(	ZDB *	db,
		const char *	filepath,
		ZDB_KEY_HDR *	key_hdr
	)

查询键存储头的状态

参数

db	{ZDB*}
filepath	{const char*} 键存储文件全路径
key_hdr	{ZDB_KEY_HDR*} 用来存放键存储头信息的内存地址

返回

{int} 0: ok; -1: error

zdb_key_store_close()

ACL_API void zdb_key_store_close

(

ZDB_KEY_STORE *

store

)

关闭键存储

参数

store

{ZDB_KEY_STORE*} 键存储句柄

zdb_key_store_open()

ACL_API ZDB_KEY_STORE* zdb_key_store_open	(	ZDB *	db,
		zdb_key_t	key
	)

根据键值打开键存储

参数

db	{ZDB*}
key	{zdb_key_t} 键值

返回

{ZDB_KEY_STORE*} !NULL: ok; NULL: error

zdb_key_store_open2()

ACL_API ZDB_KEY_STORE* zdb_key_store_open2	(	ZDB *	db,
		const char *	filepath
	)

根据文件名打开键存储

参数

db	{ZDB*}
filepath	{const char*} 文件名

返回

{ZDB_KEY_STORE*} !NULL: ok; NULL: error

zdb_key_walk()

ACL_API int zdb_key_walk	(	ZDB *	db,
		int(*)(ZDB_KEY_STORE *store)	walk_fn
	)

zdb_lookup()

ACL_API ZDB_BLK* zdb_lookup	(	ZDB *	db,
		zdb_key_t	key,
		size_t *	size,
		ZDB_BLK_OFF *	blk_off_buf
	)

在 ZDB 数据库中查找相应键值的数据

参数

db	{ZDB*} ZDB 数据库句柄
key	{zdb_key_t} 键值
size	{size_t*} 若此指针非空且查询结果也非空则存储查询结果的数据长度, 即是 ZDB_BLK.dat 中存储数据的长度
blk_off_buf	{ZDB_BLK_OFF*} 若非空则存储所查值的偏移位置索引号

返回

{ZDB_BLK*} NULL: 未找到; !NULL: ZDB_BLK->dat 为用户数据的地址, 其中 ZDB_BLK 对象可以用 acl_myfree()/1 进行释放 注意: 当 size 指针地址非空时，调用者的类型必须是 size_t 类型而非 int 类型，因为在 64位机上 size_t 为8个字节长度，而 int 为4个字节长度，内部在对 size 地址赋值 时，编译器会自动按 size_t 的真实空间长度赋值，如果调用者的 size 为 int 类型， 则就会出现空间越办现象，从而会使整个程序出现莫名其妙的问题，并且用 valgrind 也查不出这个错误来!

zdb_open()

ACL_API ZDB* zdb_open	(	const char *	dbname,
		unsigned int	oflags,
		const ZDB_CFG *	cfg
	)

打开或创建一个 ZDB 数据库

参数

dbname	{const char*} ZDB 数据库名称
oflags	{unsigned int} 打开 ZDB 库时的标志位
cfg	{const ZDB_CFG*} 打开 ZDB 时的配置对象

返回

{ZDB*} ZDB 数据库句柄

zdb_sync()

ACL_API void zdb_sync

(

ZDB *

db

)

更新ZDB相关信息至磁盘

参数

db

{ZDB*}

zdb_test()

ACL_API void zdb_test

(

const char *

cmd

)

zdb 测试函数

zdb_update()

ACL_API int zdb_update	(	ZDB *	db,
		zdb_key_t	key,
		const ZDB_BLK_OFF *	blk_off_saved,
		const void *	dat,
		size_t	len
	)

添加或更新 ZDB 数据库中的数据

参数

db	{ZDB*} ZDB 数据库句柄
key	{zdb_key_t} 键值
blk_off_saved	{const ZDB_BLK_OFF*} 上次调用 zdb_lookup()/4 时的返回结果, 从而通过重复利用查询结果来提高效率, 如果在调用 zdb_lookup()/4 时返回结果为空, 则调用 zdb_update()/5 时必须将此值置 NULL
dat	{const void*} 键 key 所对应的数据地址
len	{size_t} dat 数据长度

返回

{int} 0: 未更新或添加; -1: 出错; 1: 成功