Zookeeper C API 指南五(同步 API 介绍)

上一讲《Zookeeper C API 指南四(C API 概览)》讲了Zookeeper C API 的分类和几个基本函数的用法，相信大家对 Zookeeper C API 也有了一个大致的了解，本文我会给大家介绍 Zookeeper C API 中的同步调用的函数(即以 zoo_* 开头的函数)。

Zookeeper C API 中与访问 Zookeeper 服务相关(比如创建、删除 znode 节点，获取子节点，设置 znode 数据等)的同步 API 如下：

ZOOAPI int zoo_add_auth(zhandle_t * zh, const char *scheme,
const char *cert, int certLen,
void_completion_t completion, const void *data);

ZOOAPI int zoo_create(zhandle_t * zh, const char *path,
const char *value, int valuelen,
const struct ACL_vector *acl, int flags,
char *path_buffer, int path_buffer_len);

ZOOAPI int zoo_delete(zhandle_t * zh, const char *path, int version);

ZOOAPI int zoo_exists(zhandle_t * zh, const char *path, int watch,
struct Stat *stat);

ZOOAPI int zoo_wexists(zhandle_t * zh, const char *path,
watcher_fn watcher, void *watcherCtx,
struct Stat *stat);

ZOOAPI int zoo_get(zhandle_t * zh, const char *path, int watch,
char *buffer, int *buffer_len, struct Stat *stat);

ZOOAPI int zoo_wget(zhandle_t * zh, const char *path,
watcher_fn watcher, void *watcherCtx,
char *buffer, int *buffer_len, struct Stat *stat);

ZOOAPI int zoo_set(zhandle_t * zh, const char *path,
const char *buffer, int buflen, int version);

ZOOAPI int zoo_set2(zhandle_t * zh, const char *path,
const char *buffer, int buflen, int version,
struct Stat *stat);

ZOOAPI int zoo_get_children(zhandle_t * zh, const char *path,
int watch, struct String_vector *strings);

ZOOAPI int zoo_wget_children(zhandle_t * zh, const char *path,
watcher_fn watcher, void *watcherCtx,
struct String_vector *strings);

ZOOAPI int zoo_get_children2(zhandle_t * zh, const char *path,
int watch, struct String_vector *strings,
struct Stat *stat);

ZOOAPI int zoo_wget_children2(zhandle_t * zh, const char *path,
watcher_fn watcher, void *watcherCtx,
struct String_vector *strings,
struct Stat *stat);

ZOOAPI int zoo_get_acl(zhandle_t * zh, const char *path,
struct ACL_vector *acl, struct Stat *stat);

ZOOAPI int zoo_set_acl(zhandle_t * zh, const char *path, int version,
const struct ACL_vector *acl);

ZOOAPI int zoo_multi(zhandle_t * zh, int count, const zoo_op_t * ops,
zoo_op_result_t * results);

本文将以上同步 API 在此细分为一下几类：(1). 创建、删除 znode 节点，(2). 可设置 watch 的 API，(3). 访问、设置节点 ACL 的 API，(4). 批处理 API

创建、删除 znode 节点(两个)

ZOOAPI int zoo_create(zhandle_t * zh, const char *path,
const char *value, int valuelen,
const struct ACL_vector *acl, int flags,
char *path_buffer, int path_buffer_len);

ZOOAPI int zoo_delete(zhandle_t * zh, const char *path, int version);

创建 znode 节点：

ZOOAPI int zoo_create(zhandle_t * zh, const char *path,
const char *value, int valuelen,
const struct ACL_vector *acl, int flags,
char *path_buffer, int path_buffer_len);

zh	[b]zookeeper_init() [b]返回的 zookeeper 句柄。[/b][/b]
path	[b]节点路径。[/b]
value	[b]该节点保存的数据。[/b]
valuelen	[b]该节点保存数据的大小。如果 value 被设置为 NULL(该 znode 节点不包含数据)，则 valuelen 应该设置为 -1。[/b]
acl	[b]该节点初始 ACL,ACL 不能为null 或空。[/b]
flags	[b]该参数可以设置为 0，或者创建标识符 [b]ZOO_EPHEMERAL, ZOO_SEQUENCE 的组合或(OR)。[/b][/b]
path_buffer	用于保存返回节点新路径（因为设置了 [b]ZOO_SEQUENCE 后 zoo_create 所创建的节点名称与参数 path 提供的名称不同，新的节点名称后面填充了序号），path 字符串以 NULL 结束。path_buffer 可以设置为 NULL，此时 path_buffer_len 等于 0。 [/b]
path_buffer_len	path_buffer 的长度，如果新节点名称的长度大于path_buffer_len，则节点名称将会被截断，而服务器端该节点的名称不会截断。

删除 znode 节点：

ZOOAPI int zoo_delete(zhandle_t * zh, const char *path, int version);

zh	[b]zookeeper_init() [b]返回的 zookeeper 句柄。[/b][/b]
path	[b][b]节点路径。[/b][/b]
version	节点的版本号，如果该 znode 节点的实际版本号与该参数提供的版本号不一值，则删除节点失败，如果 version 为 -1，则不作版本检查。

可设置 watch 的 API(exists(两个) + get(两个) + get_children(四个) = 八个)

ZOOAPI int zoo_exists(zhandle_t * zh, const char *path, int watch,
struct Stat *stat);

ZOOAPI int zoo_wexists(zhandle_t * zh, const char *path,
watcher_fn watcher, void *watcherCtx,
struct Stat *stat);

ZOOAPI int zoo_get(zhandle_t * zh, const char *path, int watch,
char *buffer, int *buffer_len, struct Stat *stat);

ZOOAPI int zoo_wget(zhandle_t * zh, const char *path,
watcher_fn watcher, void *watcherCtx,
char *buffer, int *buffer_len, struct Stat *stat);

ZOOAPI int zoo_get_children(zhandle_t * zh, const char *path,
int watch, struct String_vector *strings);

ZOOAPI int zoo_wget_children(zhandle_t * zh, const char *path,
watcher_fn watcher, void *watcherCtx,
struct String_vector *strings);

ZOOAPI int zoo_get_children2(zhandle_t * zh, const char *path,
int watch, struct String_vector *strings,
struct Stat *stat);

ZOOAPI int zoo_wget_children2(zhandle_t * zh, const char *path,
watcher_fn watcher, void *watcherCtx,
struct String_vector *strings,
struct Stat *stat);

检查节点状态 exists(两个，分别是 zoo_exists() 和 zoo_wexists()，区别是后者可以指定单独的 watcher_fn(监视器回调函数)，而前者只能用 zookeeper_init() 设置的全局监视器回调函数，同时 get 和 get_children两族函数也一样，带有zoo_w* 的函数可以指定单独的 watcher_fn)。

ZOOAPI int zoo_exists(zhandle_t * zh, const char *path, int watch, struct Stat *stat);

zh	[b]zookeeper_init() [b]返回的 zookeeper 句柄。[/b][/b]
path	节点路径。
watch	如果非 0，则在服务器端设置监视，当节点发生变化时客户端会得到通知，即使当前指定的节点不存在也会设置监视，这样该节点被创建时，客户端也可以得到通知。
[b]stat[/b]	返回的 Stat 信息。

ZOOAPI int zoo_wexists(zhandle_t * zh, const char *path, watcher_fn watcher, void *watcherCtx,
struct Stat *stat);

zh	[b]zookeeper_init() [b]返回的 zookeeper 句柄。[/b][/b]
path	[b]节点路径。[/b]
watcher	如果不为 NULL 则会在服务器端设置监视，[b]当节点发生变化时客户端会得到通知，即使当前指定的节点不存在也会设置监视，这样该节点被创建时，客户端也可以得到通知。[/b]
watcherCtx	用户指定的数据，将被传入到监视器回调函数中，与由 zookeeper_init() 设置的全局监视器上下文不同，该函数设置的监视器上下文只与当前的监视器相关联。
[b][b]stat[/b][/b]	[b]返回的 Stat 信息。[/b]

获取节点数据 get(两个)

ZOOAPI int zoo_get(zhandle_t * zh, const char *path, int watch,
char *buffer, int *buffer_len, struct Stat *stat);

zh	[b]zookeeper_init() [b]返回的 zookeeper 句柄。[/b][/b]
path	[b][b]节点路径。[/b][/b]
watch	如果非0，[b]则在服务器端设置监视，当节点发生变化时客户端会得到通知。[/b]
buffer	用于保存从 zookeeper 服务器获取的节点数据。
buffer_len	buffer 大小，一旦成功返回该值将会被设置为节点数据的实际大小，如果节点的数据为空，则数据大小为 -1，buffer_len 也为 -1。
stat	如果非空，stat 指向的结构将会保存该节点的 Stat 信息。

ZOOAPI int zoo_wget(zhandle_t * zh, const char *path,
watcher_fn watcher, void *watcherCtx,
char *buffer, int *buffer_len, struct Stat *stat);

zh	[b]zookeeper_init() [b]返回的 zookeeper 句柄。[/b][/b]
path	[b][b][b]节点路径。[/b][/b][/b]
watcher	[b]如果不为 NULL 则会在服务器端设置监视，[b]当节点发生变化时客户端会得到通知[/b]。[/b]
watcherCtx	[b]用户指定的数据，将被传入到监视器回调函数中，与由 zookeeper_init() 设置的全局监视器上下文不同，该函数设置的监视器上下文只与当前的监视器相关联。[/b]
buffer	[b]用于保存从 zookeeper 服务器获取的节点数据。[/b]
buffer_len	[b]buffer 大小，一旦成功返回该值将会被设置为节点数据的实际大小，如果节点的数据为空，则数据大小为 -1，buffer_len 也为 -1。[/b]
stat	[b]如果非空，stat 指向的结构将会保存该节点的 Stat 信息。[/b]

获取子节点列表 get_children(四个)

ZOOAPI int zoo_get_children(zhandle_t * zh, const char *path,
int watch, struct String_vector *strings);

zh	[b]zookeeper_init() [b]返回的 zookeeper 句柄。[/b][/b]
path	[b][b][b][b]节点路径。[/b][/b][/b][/b]
watch	[b]如果非0，[b]则在服务器端设置监视，当节点发生变化时客户端会得到通知。[/b][/b]
strings	返回各个子节点路径

ZOOAPI int zoo_wget_children(zhandle_t * zh, const char *path, watcher_fn watcher, void *watcherCtx,
struct String_vector *strings);

zh	[b]zookeeper_init() [b]返回的 zookeeper 句柄。[/b][/b]
path	[b][b][b][b][b]节点路径。[/b][/b][/b][/b][/b]
watcher	[b][b]如果不为 NULL 则会在服务器端设置监视，[b]当节点发生变化时客户端会得到通知[/b]。[/b][/b]
watcherCtx	[b][b]用户指定的数据，将被传入到监视器回调函数中，与由 zookeeper_init() 设置的全局监视器上下文不同，该函数设置的监视器上下文只与当前的监视器相关联。[/b][/b]
strings	[b]回各个子节点路径[/b]

ZOOAPI int zoo_get_children2(zhandle_t * zh, const char *path, int watch, struct String_vector *strings,
struct Stat *stat);

该函数最早出现在 Zookeeper 3.3.0中，该函数功能与 zoo_get_children() 基本一致，但同时还会返回指定节点的 Stat 信息。

zh	[b]zookeeper_init() [b]返回的 zookeeper 句柄。[/b][/b]
path	[b][b][b][b][b][b]节点路径。[/b][/b][/b][/b][/b][/b]
watch	[b][b]如果非0，[b]则在服务器端设置监视，当节点发生变化时客户端会得到通知。[/b][/b][/b]
strings	[b]返回各个子节点路径。[/b]
stat	返回指定节点的 Stat 信息。

ZOOAPI int zoo_wget_children2(zhandle_t * zh, const char *path,
watcher_fn watcher, void *watcherCtx,
struct String_vector *strings,
struct Stat *stat);

该函数最早出现在 Zookeeper 3.3.0中，该函数功能与 zoo_wget_children() 基本一致，但同时还会返回指定节点的 Stat 信息。

zh	[b]zookeeper_init() [b]返回的 zookeeper 句柄。[/b][/b]
path	[b][b][b][b][b][b][b]节点路径。[/b][/b][/b][/b][/b][/b][/b]
watcher	[b][b][b]如果不为 NULL 则会在服务器端设置监视，[b]当节点发生变化时客户端会得到通知[/b]。[/b][/b][/b]
watcherCtx	[b][b][b]用户指定的数据，将被传入到监视器回调函数中，与由 zookeeper_init() 设置的全局监视器上下文不同，该函数设置的监视器上下文只与当前的监视器相关联。[/b][/b][/b]
strings	[b][b]返回各个子节点路径。[/b][/b]
stat	[b]返回指定节点的 Stat 信息。[/b]

访问、设置节点 ACL (两个)

ZOOAPI int zoo_get_acl(zhandle_t * zh, const char *path, struct ACL_vector *acl, struct Stat *stat);

ZOOAPI int zoo_set_acl(zhandle_t * zh, const char *path, int version, const struct ACL_vector *acl);

获取节点 ACL 信息

ZOOAPI int zoo_get_acl(zhandle_t * zh, const char *path, struct ACL_vector *acl, struct Stat *stat);

zh	[b]zookeeper_init() [b]返回的 zookeeper 句柄。[/b][/b]
path	节点路径。
acl	该函数所返回的指定节点的 ACL 信息。
stat	[b][b]返回指定节点的 Stat 信息。[/b][/b]

设置节点 ACL

ZOOAPI int zoo_set_acl(zhandle_t * zh, const char *path, int version, const struct ACL_vector *acl);

zh	[b]zookeeper_init() [b]返回的 zookeeper 句柄。[/b][/b]
path	[b]节点路径。[/b]
version	节点的版本号。
acl	需要设置的 ACL 信息。

批处理，即原子性地一次提交多个 Zookeeper 操作。

ZOOAPI int zoo_multi(zhandle_t * zh, int count, const zoo_op_t * ops, zoo_op_result_t * results);

zh	[b]zookeeper_init() [b]返回的 zookeeper 句柄。[/b][/b]
count	提交操作的个数。
ops	包含所提交操作数组。
results	包含操作所返回结果的数组。

其中 zoo_op_t 是各种操作(创建、删除节点，设置节点数据和检查节点状态四种操作)一个封装(联合体)，定义如下：

typedef struct zoo_op {
int type;
union {
// CREATE
struct {
const char *path;
const char *data;
int datalen;
char *buf;
int buflen;
const struct ACL_vector *acl;
int flags;
} create_op;

// DELETE
struct {
const char *path;
int version;
} delete_op;

// SET
struct {
const char *path;
const char *data;
int datalen;
int version;
struct Stat *stat;
} set_op;

// CHECK
struct {
const char *path;
int version;
} check_op;
};
} zoo_op_t;

zoo_op_t 一般由以下四个函数初始化：

void zoo_create_op_init(zoo_op_t * op, const char *path, const char *value,
int valuelen, const struct ACL_vector *acl,
int flags, char *path_buffer, int path_buffer_len);

void zoo_delete_op_init(zoo_op_t * op, const char *path, int version);

void zoo_set_op_init(zoo_op_t * op, const char *path,
const char *buffer, int buflen, int version,
struct Stat *stat);

void zoo_check_op_init(zoo_op_t * op, const char *path, int version);

zoo_op_result_t 用于保存 zoo_multi 或者 zoo_amulti 返回的其中一个结果，定义如下：

typedef struct zoo_op_result {
int err;
char *value;
int valuelen;
struct Stat *stat;
} zoo_op_result_t;

以上内容是 Zookeeper C API 中同步 API 的介绍，如有错误请留下您的想法和意见，本人会尽快更正；同时，我也将在后面的文章中列举一些示例来说明上述 API 的用法，如有兴趣请继续关注，如果您需要了解 Zookeeper 异步 API，请移步第六讲《Zookeeper C API 指南六(异步 API 介绍)》。