Zookeeper C API 指南六(异步 API 介绍)

转载地址：https://www.cnblogs.com/haippy/archive/2013/02/21/2920426.html

上一讲《Zookeeper C API 指南五(同步 API 介绍)》讲了Zookeeper 同步 API 的分类和相关解释，相信大家对 Zookeeper 同步 API 也有了一个大致的了解，本文我会给大家介绍 Zookeeper C API 中的异步调用的函数(即以 zoo_a* 开头的函数)，本文大致结构与《Zookeeper C API 指南五(同步 API 介绍)》，先汇总 API，然后再分类，并对每个 API 作出解释。

在具体讲解 Zookeeper 异步 API 之前，首先回顾一下《Zookeeper C API 指南三(回调函数)》，除了监视器回调函数以外，还有其他 7 种回调函数，他们通常在异步 API 调用结束或 Zookeeper 客户端失去连接时被调用。根据回调函数返回参数(即函数的输出参数)的类型不同分为以下几类：返回 void 类型的回调函数，返回 Stat 结构的回调函数，返回字符串的回调函数，返回数据的回调函数，返回字符串列表(a list of string)的回调函数，同时返回字符串列表(a list of string)和 Stat 结构的回调函数，以及返回 ACL 信息的回调函数，7 中回调函数原型声明如下：

// 返回 void 类型的回调函数
typedef void(* void_completion_t)(int rc, const void *data);// 返回 Stat 结构的回调函数
typedef void(* stat_completion_t)(int rc, const struct Stat *stat, const void *data); // 返回字符串的回调函数
typedef void(* string_completion_t)(int rc, const char *value, const void *data); // 返回数据的回调函数
typedef void(* data_completion_t)(int rc, const char *value, int value_len, const struct Stat *stat, const void *data); // 返回字符串列表(a list of string)的回调函数
typedef void(* strings_completion_t)(int rc, const struct String_vector *strings, const void *data); // 同时返回字符串列表(a list of string)和 Stat 结构的回调函数
typedef void(* strings_stat_completion_t)(int rc, const struct String_vector *strings, const struct Stat *stat, const void *data); // 以及返回 ACL 信息的回调函数
typedef void(* acl_completion_t)(int rc, struct ACL_vector *acl, struct Stat *stat, const void *data);

可能这么说还不是很理解，那么我们以异步创建 znode 节点(zoo_acreate())为例解释一下：

zoo_acreate函数原型如下：

ZOOAPI int zoo_acreate(zhandle_t * zh, const char *path,const char *value, int valuelen,const struct ACL_vector *acl, int flags,string_completion_t completion, const void *data);

其中参数 string_completion_t completion 即返回字符串的回调函数，那么当 zoo_acreate 调用结束时将会触发 completion 回调函数的调用，同时传递给 completion 的 rc 参数为: ZOK 操作完成；ZNONODE 父节点不存在；ZNODEEXISTS 节点已存在；ZNOAUTH 客户端没有权限创建节点。ZNOCHILDRENFOREPHEMERALS 临时节点不能创建子节点。而 string_completion_t completion 中 const char *value 参数即新节点的路径名（注：如果 zoo_acreate 设置了ZOO_EPHEMERAL，则创建节点成功后，节点名称并不是 zoo_acreate 中 path 参数所指定的名称，而是类似与 /xyz0000000001,/xyz0000000002... 的名称）。另外，string_completion_t completion 中 const void *data 参数即为 zoo_acreate 中的 const void *data。

一般来说，zoo_acreate 函数可以按照以下方式调用：

    int ret = zoo_acreate(zkhandle, "/xyz", "hello", 5,&ZOO_OPEN_ACL_UNSAFE, 0 /* ZOO_SEQUENCE */,zktest_string_completion, "acreate");if (ret) {fprintf(stderr, "Error %d for %s\n", ret, "acreate");exit(EXIT_FAILURE);}

其中 zktest_string_completion 功能很简单，就是把创建成功后的节点名称打印出来，函数定义如下：

void zktest_string_completion(int rc, const char *name, const void *data)
{fprintf(stderr, "[%s]: rc = %d\n", (char*)(data==0?"null":data), rc);if (!rc) {fprintf(stderr, "\tname = %s\n", name);}
}

好了，有了上面的基础，我们接下来再来讲讲 Zookeeper 异步 API 吧 :-)

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

ZOOAPI int zoo_acreate(zhandle_t * zh, const char *path,const char *value, int valuelen,const struct ACL_vector *acl, int flags,string_completion_t completion, const void *data);ZOOAPI int zoo_adelete(zhandle_t * zh, const char *path, int version,void_completion_t completion, const void *data);ZOOAPI int zoo_aexists(zhandle_t * zh, const char *path, int watch,stat_completion_t completion, const void *data);ZOOAPI int zoo_awexists(zhandle_t * zh, const char *path,watcher_fn watcher, void *watcherCtx,stat_completion_t completion, const void *data);ZOOAPI int zoo_aget(zhandle_t * zh, const char *path, int watch,data_completion_t completion, const void *data);ZOOAPI int zoo_awget(zhandle_t * zh, const char *path,watcher_fn watcher, void *watcherCtx,data_completion_t completion, const void *data);ZOOAPI int zoo_aset(zhandle_t * zh, const char *path,const char *buffer, int buflen, int version,stat_completion_t completion, const void *data);ZOOAPI int zoo_aget_children(zhandle_t * zh, const char *path,int watch,strings_completion_t completion,const void *data);ZOOAPI int zoo_awget_children(zhandle_t * zh, const char *path,watcher_fn watcher, void *watcherCtx,strings_completion_t completion,const void *data);ZOOAPI int zoo_aget_children2(zhandle_t * zh, const char *path,int watch,strings_stat_completion_t completion,const void *data);ZOOAPI int zoo_awget_children2(zhandle_t * zh, const char *path,watcher_fn watcher, void *watcherCtx,strings_stat_completion_t completion,const void *data);ZOOAPI int zoo_async(zhandle_t * zh, const char *path,string_completion_t completion, const void *data);ZOOAPI int zoo_aget_acl(zhandle_t * zh, const char *path,acl_completion_t completion, const void *data);ZOOAPI int zoo_aset_acl(zhandle_t * zh, const char *path, int version,struct ACL_vector *acl, void_completion_t,const void *data);ZOOAPI int zoo_amulti(zhandle_t * zh, int count, const zoo_op_t * ops,zoo_op_result_t * results, void_completion_t,const void *data);

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

创建、删除 znode 节点

ZOOAPI int zoo_acreate(zhandle_t * zh, const char *path,const char *value, int valuelen,const struct ACL_vector *acl, int flags,string_completion_t completion, const void *data);ZOOAPI int zoo_adelete(zhandle_t * zh, const char *path, int version,void_completion_t completion, const void *data);

创建 znode 节点

ZOOAPI int zoo_acreate(zhandle_t * zh, const char *path,const char *value, int valuelen,const struct ACL_vector *acl, int flags,string_completion_t completion, const void *data);

zh	zookeeper_init() 返回的 zookeeper 句柄。
path	节点路径。
value	该节点保存的数据。
valuelen	该节点保存数据的大小。
acl	该节点初始 ACL,ACL 不能为null 或空。
flags	该参数可以设置为 0，或者创建标识符 ZOO_EPHEMERAL, ZOO_SEQUENCE 的组合或(OR)。
completion	当创建节点请求完成时会调用该函数，该函数原型详见第三讲《回调函数》一节。同时传递给completion的 rc参数为: ZOK 操作完成；ZNONODE 父节点不存在；ZNODEEXISTS 节点已存在；ZNOAUTH 客户端没有权限创建节点。ZNOCHILDRENFOREPHEMERALS 临时节点不能创建子节点。
data	completion 函数被调用时，传递给 completion 的数据。

删除 znode 节点

ZOOAPI int zoo_adelete(zhandle_t * zh, const char *path, int version,void_completion_t completion, const void *data);

zh	zookeeper_init() 返回的 zookeeper 句柄。
path	节点路径。
version	期望的节点版本号，如果真实的版本号与期望的版本号不同则 zoo_delete() 调用失败，-1 表示不不检查版本号。
completion	当删除节点请求完成时会调用该函数，该函数原型详见第三讲《回调函数》一节。同时传递给completion的 rc参数为: ZOK 操作完成；ZNONODE 节点不存在；ZNOAUTH 客户端没有权限删除节点；ZBADVERSION 版包号不匹配；ZNOTEMPTY 当前节点存在子节点，不能被删除。
data	completion 函数被调用时，传递给 completion 的数据。

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

ZOOAPI int zoo_aexists(zhandle_t * zh, const char *path, int watch,stat_completion_t completion, const void *data);ZOOAPI int zoo_awexists(zhandle_t * zh, const char *path,watcher_fn watcher, void *watcherCtx,stat_completion_t completion, const void *data);ZOOAPI int zoo_aget(zhandle_t * zh, const char *path, int watch,data_completion_t completion, const void *data);ZOOAPI int zoo_awget(zhandle_t * zh, const char *path,watcher_fn watcher, void *watcherCtx,data_completion_t completion, const void *data);ZOOAPI int zoo_aget_children(zhandle_t * zh, const char *path,int watch,strings_completion_t completion,const void *data);ZOOAPI int zoo_awget_children(zhandle_t * zh, const char *path,watcher_fn watcher, void *watcherCtx,strings_completion_t completion,const void *data);ZOOAPI int zoo_aget_children2(zhandle_t * zh, const char *path,int watch,strings_stat_completion_t completion,const void *data);ZOOAPI int zoo_awget_children2(zhandle_t * zh, const char *path,watcher_fn watcher, void *watcherCtx,strings_stat_completion_t completion,const void *data);

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

ZOOAPI int zoo_aexists(zhandle_t * zh, const char *path, int watch,stat_completion_t completion, const void *data);

zh	zookeeper_init() 返回的 zookeeper 句柄。
path	节点路径。
watch	如果非 0，则在服务器端设置监视，当节点发生变化时客户端会得到通知，即使当前指定的节点不存在也会设置监视，这样该节点被创建时，客户端也可以得到通知。
completion	当 zoo_aexists 请求完成时会调用该函数，该函数原型详见第三讲《回调函数》一节。同时传递给completion的 rc参数为: ZOK 操作完成；ZNONODE 节点不存在；ZNOAUTH 客户端没有权限删除节点。
data	completion 函数被调用时，传递给 completion 的数据。

ZOOAPI int zoo_awexists(zhandle_t * zh, const char *path,watcher_fn watcher, void *watcherCtx,stat_completion_t completion, const void *data);

zh	zookeeper_init() 返回的 zookeeper 句柄。
path	节点路径。
watcher	如果非 0，则在服务器端设置监视，当节点发生变化时客户端会得到通知，即使当前指定的节点不存在也会设置监视，这样该节点被创建时，客户端也可以得到通知。
watcherCtx	用户指定的数据，将被传入到监视器回调函数中，与由 zookeeper_init() 设置的全局监视器上下文不同，该函数设置的监视器上下文只与当前的监视器相关联。
completion	当 zoo_awexists 请求完成时会调用该函数，该函数原型详见第三讲《回调函数》一节。同时传递给completion的 rc参数为: ZOK 操作完成；ZNONODE 节点不存在；ZNOAUTH 客户端没有权限删除节点。
data	completion 函数被调用时，传递给 completion 的数据。

获取节点数据 aget(两个)

ZOOAPI int zoo_aget(zhandle_t * zh, const char *path, int watch,data_completion_t completion, const void *data);

zh	zookeeper_init() 返回的 zookeeper 句柄。
path	节点路径。
watch	如果非 0，则在服务器端设置监视，当节点发生变化时客户端会得到通知。
completion	当 zoo_aget 请求完成时会调用该函数，该函数原型详见第三讲《回调函数》一节。同时传递给completion的 rc参数为: ZOK 操作完成；ZNONODE 节点不存在；ZNOAUTH 客户端没有权限删除节点。
data	completion 函数被调用时，传递给 completion 的数据。

ZOOAPI int zoo_awget(zhandle_t * zh, const char *path,watcher_fn watcher, void *watcherCtx,data_completion_t completion, const void *data);

zh	zookeeper_init() 返回的 zookeeper 句柄。
path	节点路径。
watcher	如果非 0，则在服务器端设置监视，当节点发生变化时客户端会得到通知，即使当前指定的节点不存在也会设置监视，这样该节点被创建时，客户端也可以得到通知。
watcherCtx	用户指定的数据，将被传入到监视器回调函数中，与由 zookeeper_init() 设置的全局监视器上下文不同，该函数设置的监视器上下文只与当前的监视器相关联。
completion	当 zoo_awget 请求完成时会调用该函数，该函数原型详见第三讲《回调函数》一节。同时传递给completion的 rc参数为: ZOK 操作完成；ZNONODE 节点不存在；ZNOAUTH 客户端没有权限删除节点。
data	completion 函数被调用时，传递给 completion 的数据。

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

ZOOAPI int zoo_aget_children(zhandle_t * zh, const char *path,int watch,strings_completion_t completion,const void *data);

zh	zookeeper_init() 返回的 zookeeper 句柄。
path	节点路径。
watch	如果非 0，则在服务器端设置监视，当节点发生变化时客户端会得到通知。
completion	当 zoo_aget_children 请求完成时会调用该函数，该函数原型详见第三讲《回调函数》一节。同时传递给completion的 rc参数为: ZOK 操作完成；ZNONODE 节点不存在；ZNOAUTH 客户端没有权限删除节点。
data	completion 函数被调用时，传递给 completion 的数据。

ZOOAPI int zoo_awget_children(zhandle_t * zh, const char *path,watcher_fn watcher, void *watcherCtx,strings_completion_t completion,const void *data);

zh	zookeeper_init() 返回的 zookeeper 句柄。
path	节点路径。
watcher	如果非 0，则在服务器端设置监视，当节点发生变化时客户端会得到通知，即使当前指定的节点不存在也会设置监视，这样该节点被创建时，客户端也可以得到通知。
watcherCtx	用户指定的数据，将被传入到监视器回调函数中，与由 zookeeper_init() 设置的全局监视器上下文不同，该函数设置的监视器上下文只与当前的监视器相关联。
completion	当zoo_awget_children 请求完成时会调用该函数，该函数原型详见第三讲《回调函数》一节。同时传递给completion的 rc参数为: ZOK 操作完成；ZNONODE 节点不存在；ZNOAUTH 客户端没有权限删除节点。
data	completion 函数被调用时，传递给 completion 的数据。

ZOOAPI int zoo_aget_children2(zhandle_t * zh, const char *path,int watch,strings_stat_completion_t completion,const void *data);

zh	zookeeper_init() 返回的 zookeeper 句柄。
path	节点路径。
watch	如果非 0，则在服务器端设置监视，当节点发生变化时客户端会得到通知。
completion	当 zoo_aget_children2 请求完成时会调用该函数，该函数原型详见第三讲《回调函数》一节。同时传递给completion的 rc参数为: ZOK 操作完成；ZNONODE 节点不存在；ZNOAUTH 客户端没有权限删除节点。
data	completion 函数被调用时，传递给 completion 的数据。

ZOOAPI int zoo_awget_children2(zhandle_t * zh, const char *path,watcher_fn watcher, void *watcherCtx,strings_stat_completion_t completion,const void *data);

zh	zookeeper_init() 返回的 zookeeper 句柄。
path	节点路径。
watcher	如果非 0，则在服务器端设置监视，当节点发生变化时客户端会得到通知，即使当前指定的节点不存在也会设置监视，这样该节点被创建时，客户端也可以得到通知。
watcherCtx	用户指定的数据，将被传入到监视器回调函数中，与由 zookeeper_init() 设置的全局监视器上下文不同，该函数设置的监视器上下文只与当前的监视器相关联。
completion	当zoo_awget_children2 请求完成时会调用该函数，该函数原型详见第三讲《回调函数》一节。同时传递给completion的 rc参数为: ZOK 操作完成；ZNONODE 节点不存在；ZNOAUTH 客户端没有权限删除节点。
data	completion 函数被调用时，传递给 completion 的数据。

访问、设置节点 ACL 的 API

ZOOAPI int zoo_aget_acl(zhandle_t * zh, const char *path,acl_completion_t completion, const void *data);ZOOAPI int zoo_aset_acl(zhandle_t * zh, const char *path, int version,struct ACL_vector *acl, void_completion_t,const void *data);

访问节点 ACL

ZOOAPI int zoo_aget_acl(zhandle_t * zh, const char *path,acl_completion_t completion, const void *data);

zh	zookeeper_init() 返回的 zookeeper 句柄。
path	节点路径。
completion	当 zoo_aget_acl 请求完成时会调用该函数，该函数原型详见第三讲《回调函数》一节。同时传递给completion的 rc参数为: ZOK 操作完成；ZNONODE 节点不存在；ZNOAUTH 客户端没有权限删除节点。
data	completion 函数被调用时，传递给 completion 的数据。

设置节点 ACL

ZOOAPI int zoo_aset_acl(zhandle_t * zh, const char *path, int version,struct ACL_vector *acl, void_completion_t,const void *data);

zh	zookeeper_init() 返回的 zookeeper 句柄。
path	节点路径。
buffer	保存需要设置的 ACL。
buflen	buffer 的长度。
completion	当 zoo_aset_acl 请求完成时会调用该函数，该函数原型详见第三讲《回调函数》一节。同时传递给completion的 rc参数为: ZOK 操作完成；ZNONODE 节点不存在；ZNOAUTH 客户端没有权限删除节点;ZINVALIDACL 非法 ACL；ZBADVERSION 版本号不匹配。
data	completion 函数被调用时，传递给 completion 的数据。

异步批处理 API

ZOOAPI int zoo_amulti(zhandle_t * zh, int count, const zoo_op_t * ops,zoo_op_result_t * results, void_completion_t,const void *data);

异步批处理与同步批处理方式类似见《Zookeeper C API 指南五(同步 API 介绍)》，只是需要额外设置一个 void_completion_t 回调函数，在此不再赘述。

Zookeeper C API 指南六(异步 API 介绍)相关推荐

Zookeeper C API 指南
以前自己的博客中转载.翻译或写过(不过自己才疏学浅,写的不好)一些 Zookeeper 方面的文章,但是都没有涉及到 Zookeeper C API 的内容,今天的这篇博客是我农历新年的第一篇技术博客 ...
Zookeeper C 异步 API 介绍
在讲解 Zookeeper 异步 API ,除了监视器回调函数以外,还有其他 7 种回调函数,他们通常在异步 API 调用结束或 Zookeeper 客户端失去连接时被调用.根据回调函数返回参数(即 ...
Zookeeper C API 指南一(转)
Zookeeper 监视(Watches) 简介 Zookeeper C API 的声明和描述在 include/zookeeper.h 中可以找到,另外大部分的 Zookeeper C API 常量 ...
trident API指南
trident API指南 @(STORM)[storm] trident API指南零概述 1 本地分区操作 2 重新分区操作 3 聚合操作 4 流分组操作 5合并与连接一本地分区操作一 ...
C++11 并发指南六(atomic 类型详解四 C 风格原子操作介绍)
前面三篇文章<C++11 并发指南六(atomic 类型详解一 atomic_flag 介绍)>.<C++11 并发指南六( <atomic> 类型详解二 std::at ...
push api v3_充分利用Push API的指南
push api v3 Interested in learning JavaScript? Get my ebook at jshandbook.com 有兴趣学习JavaScript吗? 在jsh ...
阿里云API网关（6）用户指南（开放 API ）
网关指南: https://help.aliyun.com/document_detail/29487.html?spm=5176.doc48835.6.550.23Oqbl 网关控制台: https ...
Microsoft REST API指南
经过3个月的碎片时间的翻译和校验,由长沙.NET技术社区翻译的英文原文文档<Microsoft REST API指南 >已经翻译完成,现刊载前十一章如下,欢迎大家点击"查看原文& ...
现代浏览器观察者 Observer API 指南
前言前段时间在研究前端异常监控/埋点平台的实现. 在思考方案时,想到了浏览器自带的观察者以及页面生命周期API . 于是在翻查资料时意外发现,原来现代浏览器支持多达四种不同类型的观察者: Inter ...

Zookeeper C API 指南六(异步 API 介绍)

Zookeeper C API 指南六(异步 API 介绍)相关推荐

最新文章

热门文章