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 中的回調函數。