Zookeeper C API 指南

以前自己的博客中转载、翻译或写过(不过自己才疏学浅，写的不好)一些 Zookeeper 方面的文章，但是都没有涉及到 Zookeeper C API 的内容，今天的这篇博客是我农历新年的第一篇技术博客，我想详细讲讲 Zookeeper C API 的使用规则和示例，算是把以前的旧帐还上吧 :-)

Zookeeper 官方页面上提供了一些编程指南和 API 文档，不过大部分都是 Java 示例，涉及 C API 的部分很少，只有在 ZooKeeper Programmer's Guide 中 ACL Permissions 一节讲了 Zookeeper C API 中设置 ACL 应该注意的事项，正是由于缺少Zookeeper C API 相关的资料，大部分 Zookeeper C/C++ 开发者只能通过阅读 Zookeeper C API 的源码来了解 C API 的使用方法，本文希望在此方面给大家提供一些便利，减少 Zookeeper 新手使用 C API 的困难和恐惧，当然我自己也是一枚新手啦 :-)。

废话不多说了，先从最基本的开始吧!

Zookeeper 伪分布式安装

首先是 Zookeeper 的安装，如果你没有足够的机器，建议在单机上通过伪分布式安装方法来模拟 Zookeeper 集群，我在这里提供给大家一个简单的安装包来降低伪分布式 Zookeeper 的安装难度，该安装包可以模拟一个 5 Zookeeper 实例的集群。下载zookeeper-3.4.0-pseudoclusters.tar.bz2，解压至 /tmp/ 目录（注意，安装包里面 dataDir 和 dataLogDir 配置已经预设为 /tmp/ 目录，如果你只是自己在 Zookeeper 上做一些小实验，建议不要更改该配置，这样在你做完了实验以后删除 /tmp/zookeeper/ 目录即可），操作方法如下：

forhappy@haiping-ict:/tmp$ pwd
/tmp
forhappy@haiping-ict:/tmp$ tar xvf zookeeper-3.4.0-pseudoclusters.tar.bz2
forhappy@haiping-ict:/tmp$ cd zookeeper/
forhappy@haiping-ict:/tmp/zookeeper$ ls
server001  server003  server005          stopZKCluster.sh
server002  server004  startZKCluster.sh

然后在 /tmp/zookeeper 目录下执行 startZKCluster.sh 启动 Zookeeper 服务，或者执行 stopZKCluster.sh 停掉 Zookeeper 服务。

启动 Zookeeper 服务：

forhappy@haiping-ict:/tmp/zookeeper$ ./startZKCluster.sh .
starting zookeeper instance server001...
JMX enabled by default
Using config: /tmp/zookeeper/server001/zookeeper-3.4.0/bin/../conf/zoo.cfg
Starting zookeeper ... STARTED
starting zookeeper instance server002...
JMX enabled by default
Using config: /tmp/zookeeper/server002/zookeeper-3.4.0/bin/../conf/zoo.cfg
Starting zookeeper ... STARTED
starting zookeeper instance server003...
JMX enabled by default
Using config: /tmp/zookeeper/server003/zookeeper-3.4.0/bin/../conf/zoo.cfg
Starting zookeeper ... STARTED
starting zookeeper instance server004...
JMX enabled by default
Using config: /tmp/zookeeper/server004/zookeeper-3.4.0/bin/../conf/zoo.cfg
Starting zookeeper ... STARTED
starting zookeeper instance server005...
JMX enabled by default
Using config: /tmp/zookeeper/server005/zookeeper-3.4.0/bin/../conf/zoo.cfg
Starting zookeeper ... STARTED

停掉 Zookeeper 服务：

forhappy@haiping-ict:/tmp/zookeeper$ ./stopZKCluster.sh .
stopping zookeeper instance server001...
JMX enabled by default
Using config: /tmp/zookeeper/server001/zookeeper-3.4.0/bin/../conf/zoo.cfg
Stopping zookeeper ... STOPPED
stopping zookeeper instance server002...
JMX enabled by default
Using config: /tmp/zookeeper/server002/zookeeper-3.4.0/bin/../conf/zoo.cfg
Stopping zookeeper ... STOPPED
stopping zookeeper instance server003...
JMX enabled by default
Using config: /tmp/zookeeper/server003/zookeeper-3.4.0/bin/../conf/zoo.cfg
Stopping zookeeper ... STOPPED
stopping zookeeper instance server004...
JMX enabled by default
Using config: /tmp/zookeeper/server004/zookeeper-3.4.0/bin/../conf/zoo.cfg
Stopping zookeeper ... STOPPED
stopping zookeeper instance server005...
JMX enabled by default
Using config: /tmp/zookeeper/server005/zookeeper-3.4.0/bin/../conf/zoo.cfg
Stopping zookeeper ... STOPPED

Zookeeper C API 安装

Zookeeper C client 的实现在 src/c 目录下，进入到该目录安装 Zookeeper C client，步骤如下：

$ ./configure
$ make
$ sudo make install

至此，基本的准备工作已经完成，你可以通过 Zookeeper 本身提供的 Shell 来操作 Zookeeper，操作方法如下，进入 /tmp/zookeeper/server001/zookeeper-3.4.0 目录，执行bin/zkCli.sh -server 127.0.0.1:2181 进入 Zookeeper shell：

forhappy@haiping-ict:/tmp/zookeeper/server001/zookeeper-3.4.0$ bin/zkCli.sh -server 127.0.0.1:2181

[zk: 127.0.0.1:2181(CONNECTED) 2] help
ZooKeeper -server host:port cmd args
    connect host:port
    get path [watch]
    ls path [watch]
    set path data [version]
    rmr path
    delquota [-n|-b] path
    quit 
    printwatches on|off
    create [-s] [-e] path data acl
    stat path [watch]
    close 
    ls2 path [watch]
    history 
    listquota path
    setAcl path acl
    getAcl path
    sync path
    redo cmdno
    addauth scheme auth
    delete path [version]
    setquota -n|-b val path

在 shell 中你可以完成基本的操作，如创建、获取、删除、设置某一节点，设置节点 ACL等，可以 zookeeper shell 中通过 help 获取相关命令的用法。

如果你按照上面的步骤完成了 Zookeeper 伪分布式的安装，并且想继续了解 Zookeeper C API 的使用方法，请继续阅读《Zookeeper C API 指南二(监视(Wathes), 基本常量和结构体介绍)》

接上一篇《Zookeeper C API 指南一(准备工作)》，本问将重点介绍 Zookeeper 监视(Watches)，以及 Zookeeper C API 中基本的常量与结构体。

Zookeeper 监视（Watches）简介

Zookeeper C API 的声明和描述在 include/zookeeper.h 中可以找到，另外大部分的 Zookeeper C API 常量、结构体声明也在 zookeeper.h 中，如果如果你在使用 C API 是遇到不明白的地方，最好看看 zookeeper.h，或者自己使用 doxygen 生成 Zookeeper C API 的帮助文档。

Zookeeper 中最有特色且最不容易理解的是监视(Watches)。Zookeeper 所有的读操作——getData(),getChildren(), 和 exists() 都可以设置监视(watch)，监视事件可以理解为一次性的触发器，官方定义如下： a watch event is one-time trigger, sent to the client that set the watch, which occurs when the data for which the watch was set changes。对此需要作出如下理解：

（一次性触发）One-time trigger

当设置监视的数据发生改变时，该监视事件会被发送到客户端，例如，如果客户端调用了 getData("/znode1", true) 并且稍后 /znode1 节点上的数据发生了改变或者被删除了，客户端将会获取到 /znode1 发生变化的监视事件，而如果 /znode1 再一次发生了变化，除非客户端再次对 /znode1 设置监视，否则客户端不会收到事件通知。
（发送至客户端）Sent to the client

Zookeeper 客户端和服务端是通过 socket 进行通信的，由于网络存在故障，所以监视事件很有可能不会成功地到达客户端，监视事件是异步发送至监视者的，Zookeeper 本身提供了保序性(ordering guarantee)：即客户端只有首先看到了监视事件后，才会感知到它所设置监视的 znode 发生了变化(a client will never see a change for which it has set a watch until it first sees the watch event). 网络延迟或者其他因素可能导致不同的客户端在不同的时刻感知某一监视事件，但是不同的客户端所看到的一切具有一致的顺序。
（被设置 watch 的数据）The data for which the watch was set

这意味着 znode 节点本身具有不同的改变方式。你也可以想象 Zookeeper 维护了两条监视链表：数据监视和子节点监视(data watches and child watches) getData() and exists() 设置数据监视，getChildren() 设置子节点监视。或者，你也可以想象 Zookeeper 设置的不同监视返回不同的数据，getData() 和 exists() 返回 znode 节点的相关信息，而 getChildren() 返回子节点列表。因此， setData() 会触发设置在某一节点上所设置的数据监视(假定数据设置成功)，而一次成功的 create() 操作则会出发当前节点上所设置的数据监视以及父节点的子节点监视。一次成功的 delete() 操作将会触发当前节点的数据监视和子节点监视事件，同时也会触发该节点父节点的child watch。

Zookeeper 中的监视是轻量级的，因此容易设置、维护和分发。当客户端与 Zookeeper 服务器端失去联系时，客户端并不会收到监视事件的通知，只有当客户端重新连接后，若在必要的情况下，以前注册的监视会重新被注册并触发，对于开发人员来说这通常是透明的。只有一种情况会导致监视事件的丢失，即：通过 exists() 设置了某个 znode 节点的监视，但是如果某个客户端在此 znode 节点被创建和删除的时间间隔内与 zookeeper 服务器失去了联系，该客户端即使稍后重新连接 zookeeper服务器后也得不到事件通知。

Zookeeper C API 常量与部分结构(struct)介绍

与 ACL 相关的结构与常量：

struct Id 结构为：

struct Id {
    char * scheme;
    char * id;
};

struct ACL 结构为：

struct ACL {
    int32_t perms;
    struct Id id;
};

struct ACL_vector 结构为：

struct ACL_vector {
    int32_t count;
    struct ACL *data;

};

与 znode 访问权限有关的常量

const int ZOO_PERM_READ; //允许客户端读取 znode 节点的值以及子节点列表。
const int ZOO_PERM_WRITE;// 允许客户端设置 znode 节点的值。
const int ZOO_PERM_CREATE; //允许客户端在该 znode 节点下创建子节点。
const int ZOO_PERM_DELETE;//允许客户端删除子节点。
const int ZOO_PERM_ADMIN; //允许客户端执行 set_acl()。
const int ZOO_PERM_ALL;//允许客户端执行所有操作，等价与上述所有标志的或(OR) 。

与 ACL IDs 相关的常量

struct Id ZOO_ANYONE_ID_UNSAFE; //(‘world’,’anyone’)
struct Id ZOO_AUTH_IDS;// (‘auth’,’’)

三种标准的 ACL

struct ACL_vector ZOO_OPEN_ACL_UNSAFE; //(ZOO_PERM_ALL,ZOO_ANYONE_ID_UNSAFE)
struct ACL_vector ZOO_READ_ACL_UNSAFE;// (ZOO_PERM_READ, ZOO_ANYONE_ID_UNSAFE)
struct ACL_vector ZOO_CREATOR_ALL_ACL; //(ZOO_PERM_ALL,ZOO_AUTH_IDS)

与 Interest 相关的常量：ZOOKEEPER_WRITE, ZOOKEEPER_READ

这两个常量用于标识感兴趣的事件并通知 zookeeper 发生了哪些事件。Interest 常量可以进行组合或（OR）来标识多种兴趣(multiple interests: write, read)，这两个常量一般用于 zookeeper_interest() 和 zookeeper_process()两个函数中。

与节点创建相关的常量：ZOO_EPHEMERAL, ZOO_SEQUENCE

zoo_create 函数标志，ZOO_EPHEMERAL 用来标识创建临时节点，ZOO_SEQUENCE 用来标识节点命名具有递增的后缀序号(一般是节点名称后填充 10 位字符的序号，如 /xyz0000000000, /xyz0000000001, /xyz0000000002, ...)，同样地，ZOO_EPHEMERAL, ZOO_SEQUENCE可以组合。

与连接状态 Stat 相关的常量

以下常量均与 Zookeeper 连接状态有关，他们通常用作监视器回调函数的参数。

ZOOAPI const int	ZOO_EXPIRED_SESSION_STATE
ZOOAPI const int	ZOO_AUTH_FAILED_STATE
ZOOAPI const int	ZOO_CONNECTING_STATE
ZOOAPI const int	ZOO_ASSOCIATING_STATE
ZOOAPI const int	ZOO_CONNECTED_STATE

与监视类型(Watch Types)相关的常量

以下常量标识监视事件的类型，他们通常用作监视器回调函数的第一个参数。

ZOO_CREATED_EVENT; // 节点被创建(此前该节点不存在)，通过 zoo_exists() 设置监视。
ZOO_DELETED_EVENT; // 节点被删除，通过 zoo_exists() 和 zoo_get() 设置监视。
ZOO_CHANGED_EVENT; // 节点发生变化，通过 zoo_exists() 和 zoo_get() 设置监视。
ZOO_CHILD_EVENT; // 子节点事件，通过zoo_get_children() 和 zoo_get_children2()设置监视。
ZOO_SESSION_EVENT; // 会话丢失
ZOO_NOTWATCHING_EVENT; // 监视被移除。

Zookeeper C API 错误码介绍 ZOO_ERRORS

ZOK	正常返回
ZSYSTEMERROR	系统或服务器端错误(System and server-side errors)，服务器不会抛出该错误，该错误也只是用来标识错误范围的，即大于该错误值，且小于 ZAPIERROR 都是系统错误。
ZRUNTIMEINCONSISTENCY	运行时非一致性错误。
ZDATAINCONSISTENCY	数据非一致性错误。
ZCONNECTIONLOSS	Zookeeper 客户端与服务器端失去连接
ZMARSHALLINGERROR	在 marshalling 和unmarshalling 数据时出现错误(Error while marshalling or unmarshalling data)
ZUNIMPLEMENTED	该操作未实现(Operation is unimplemented)
ZOPERATIONTIMEOUT	该操作超时(Operation timeout)
ZBADARGUMENTS	非法参数错误(Invalid arguments)
ZINVALIDSTATE	非法句柄状态(Invliad zhandle state)
ZAPIERROR	API 错误(API errors)，服务器不会抛出该错误，该错误也只是用来标识错误范围的，错误值大于该值的标识 API 错误，而小于该值的标识 ZSYSTEMERROR。
ZNONODE	节点不存在(Node does not exist)
ZNOAUTH	没有经过授权(Not authenticated)
ZBADVERSION	版本冲突(Version conflict)
ZNOCHILDRENFOREPHEMERALS	临时节点不能拥有子节点(Ephemeral nodes may not have children)
ZNODEEXISTS	节点已经存在(The node already exists)
ZNOTEMPTY	该节点具有自身的子节点(The node has children)
ZSESSIONEXPIRED	会话过期(The session has been expired by the server)
ZINVALIDCALLBACK	非法的回调函数(Invalid callback specified)
ZINVALIDACL	非法的ACL(Invalid ACL specified)
ZAUTHFAILED	客户端授权失败(Client authentication failed)
ZCLOSING	Zookeeper 连接关闭(ZooKeeper is closing)
ZNOTHING	并非错误，客户端不需要处理服务器的响应(not error, no server responses to process)
ZSESSIONMOVED	会话转移至其他服务器，所以操作被忽略(session moved to another server, so operation is ignored)

至此，Zookeeper C API 中的大部分的常量和结构体均已介绍完毕，下一节《Zookeeper C API 指南三(回调函数)》将介绍 Zookeeper C API 中的回调函数。

接上一篇《Zookeeper C API 指南二(监视(Wathes), 基本常量和结构体介绍)》，本文重点介绍 Zookeeper C API 中的各种回调函数。

Zookeeper C API 中各种回调函数简介

在具体介绍 Zookeeper C API 之前，首先介绍一下 Zookeeper C API 中的各种回调函数的原型：

监视函数(watch function)原型

typedef void (*watcher_fn)(zhandle_t *zh, int type, int state, const char *path,void *watcherCtx);

监视函数原型的各个参数解释如下：

zh	zookeeper 句柄(handle)
type	事件类型(event type). *_EVENT 常量之一.
state	连接状态(connection state). 状态值为 *_STATE 常量之一.
path	触发监视事件的 znode 节点的路径，若为 NULL，则事件类型为 ZOO_SESSION_EVENT
watcherCtx	监视器上下文(watcher context).

其他回调函数的原型

Zookeeper 中还有几种在异步 API(一般以 zoo_a*开头的函数) 中使用的回调函数，根据回调函数处理异步函数返回值类型的不同分为以下几类：处理返回 void 类型的回调函数，处理返回 Stat 结构的回调函数，处理返回字符串的回调函数，处理返回数据的回调函数，处理返回字符串列表(a list of string)的回调函数，同时处理返回字符串列表(a list of string)和 Stat 结构的回调函数，以及处理返回 ACL 信息的回调函数，它们分别如下：

// 处理返回 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);

下面一一介绍上述几种回调函数的用法：

处理返回 void 类型的回调函数

typedef void(* void_completion_t)(int rc, const void *data)

该回调函数一般在异步 API 调用结束或 Zookeeper 客户端失去连接时被调用。

rc 异步函数调用返回的错误码，连接丢失/超时将触发该原型函数(此处指具有该函数原型的回调函数，下同)的调用，并且错误码为 ZCONNECTIONLOSS -- Zookeeper 客户端与服务器端的连接丢失，或者 ZOPERATIONTIMEOUT -- 连接超时；而与数据相关的事件也会触发该原型函数的调用，同时置相应的错误码，具体见后文(0 代异步函数调用成功)

data 由调用者传入的指针，调用者可以通过该指针向回调函数传入自定义的参数，开发人员应负责此指针所指向内存的释放。

处理返回 Stat 结构的回调函数

typedef void(* stat_completion_t)(int rc, const struct Stat *stat, const void *data)