发布时间 : 星期日 文章zookeeper使用总结文档- 初级更新完毕开始阅读
第3章 Zookeeper C API简介
Zookeeper C API 的声明和描述在 include/zookeeper.h 中可以找到，另外大部分的 Zookeeper C API 常量、结构体声明也在 zookeeper.h 中，如果如果你在使用 C API 是遇到不明白的地方，最好看看 zookeeper.h，或者自己使用 doxygen 生成 Zookeeper C API 的帮助文档。
3.1 Watches
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 节点上的数据发生了改变或者被删除了，客户端将会获取到 /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。
6
Zookeeper 中的监视是轻量级的，因此容易设置、维护和分发。当客户端与 Zookeeper 服务器端失去联系时，客户端并不会收到监视事件的通知，只有当客户端重新连接后，若在必要的情况下，以前注册的监视会重新被注册并触发，对于开发人员来说 这通常是透明的。只有一种情况会导致监视事件的丢失，即：通过 exists() 设置了某个 znode 节点的监视，但是如果某个客户端在此 znode 节点被创建和删除的时间间隔内与 zookeeper 服务器失去了联系，该客户端即使稍后重新连接 zookeeper服务器后也得不到事件通知。
3.1.1 监视函数原型
typedef void (*watcher_fn)(zhandle_t *zh, int type, int state, const char *path,void *watcherCtx); 监视函数原型的各个参数解释如下： zh type state path zookeeper 句柄(handle) 事件类型(event type). *_EVENT 常量之一. 连接状态(connection state). 状态值为 *_STATE 常量之一. 触发监视事件的 znode 节点的路径，若为 NULL，则事件类型为 ZOO_SESSION_EVENT watcherCtx 监视器上下文(watcher context).
3.2 常用API
3.2.1.1 zookeeper_init
ZOOAPI zhandle_t *zookeeper_init(const char *host, watcher_fn fn, int recv_timeout, const clientid_t * clientid, void *context, int flags);
功能：
创建一个句柄（handle）和一个响应（response）这个句柄的会话（session）。 参数：
host：zookeeper主机列表，用逗号间隔。 fn：用于监视的回调函数。
clientid：之前建立过连接，现在要重新连的客户端（client）ID。如果之前没有，则为0.
7
context：暂时用不到，忽略。
flags：设置为0，zookeeper开发团队保留以后使用。
3.2.1.2 zookeeper_close
ZOOAPI int zookeeper_close(zhandle_t *zh);
功能：
关闭句柄，释放资源。 参数：
zh：zookeeper句柄。 返回值：
ZOK表示成功
ZBADARGUMENTS表示输入参数无效
ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory ZOPERATIONTIMEOUT - failed to flush the buffers within the specified timeout.
ZCONNECTIONLOSS - a network error occured while attempting to send request to server
ZSYSTEMERROR -- a system (OS) error occured; it's worth checking errno to get details
3.2.1.3 zoo_create
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);
功能：
创建一个同步的zookeeper节点。 参数：
zh：zookeeper的句柄，由zookeeper_init得到。 path：节点名称，就是一个类似于文件系统写法的路径。
value：欲存储到该节点的数据。如果不存储数据，则设置为NULL。 valuelen：欲存储的数据的长度。如果不存储数据，则设置为-1.
acl：初始的ACL节点，ACL不能为空。比如设置为&ZOO_OPEN_ACL_UNSAFE。 flags：一般设置为0。
path_buffer：将由新节点填充的路径值。可设置为NULL。
8
path_buffer_len：path_buffer的长度。 返回值：
ZOK表示操作成功。
ZNONODE表示该节点不存在。 ZNODEEXISTS表示节点已经存在。 ZNOAUTH表示客户端（client）无权限。
ZNOCHILDRENFOREPHEMERALS表示不能够创建临时（ephemeral）节点的子节点（children）。
3.2.1.4 zoo_wexists
ZOOAPI int zoo_wexists(zhandle_t *zh, const char *path, watcher_fn watcher,
void* watcherCtx, struct Stat *stat);
功能：
同步监视一个zookeeper节点（node）是否存在。 参数：
zh：zookeeper的句柄，由zookeeper_init得到。 path：节点名称，就是一个类似于文件系统写法的路径。
watcher：如果不为 NULL 则会在服务器端设置监视，当节点发生变化时客户端会得到通知，即使当前指定的节点不存在也会设置监视，这样该节点被创建时，客户端也可以得到通知。
watcherCtx: 用户指定的数据，将被传入到监视器回调函数中，与由 zookeeper_init() 设置的全局监视器上下文不同，该函数设置的监视器上下文只与当前的监视器相关联。 stat：返回的Stat信息 返回值：
ZOK表示操作成功。
ZNONODE表示该节点不存在。
ZNOAUTH表示客户端（client）无权限。 ZINVALIDSTATE表示存在非法的参数。
9