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 中的回调函数。