Zookeeper C API 指南三(回调函数)(转)

2013-02-21 12:54 by Haippy, 9237 阅读, 0 评论, 收藏, 编辑

接上一篇《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	由调用者传入[b][b][b][b][b][b][b]的[/b][/b][/b][/b][/b][/b]指针，[b]调用者可以通过该指针向回调函数传入自定义的参数[/b]，开发人员应负责此指针所指向内存的释放。[/b]

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

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

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

rc	异步函数调用返回的错误码，连接丢失/超时将触发该原型函数(此处指具有该函数原型的回调函数，下同)的调用，并且错误码为 ZCONNECTIONLOSS -- Zookeeper 客户端与服务器端的连接丢失，或者 ZOPERATIONTIMEOUT -- 连接超时；而与数据相关的事件也会触发该原型函数的调用，同时置相应的错误码，具体见后文(0 代异步函数调用成功)
stat	指向与该 znode 节点相关的 Stat 信息，如果返回非 0 值(即异步调用函数出错)，stat 所指向的区域是未定义的，开发者不负责释放 stat 所指向的内存空间。
data	由调用者传入[b][b][b][b][b][b][b]的[/b][/b][/b][/b][/b][/b]指针，调用者可以通过该指针向回调函数传入自定义的参数，开发人员应负责此指针所指向内存的释放。[/b]

处理返回字符串的回调函数

typedef void(* string_completion_t)(int rc, const char *value, const void *data)

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

rc	异步函数调用返回的错误码，连接丢失/超时将触发该原型函数(此处指具有该函数原型的回调函数，下同)的调用，并且错误码为 ZCONNECTIONLOSS -- Zookeeper 客户端与服务器端的连接丢失，或者 ZOPERATIONTIMEOUT -- 连接超时；而与数据相关的事件也会触发该原型函数的调用，同时置相应的错误码，具体见后文(0 代异步函数调用成功)
value	返回的字符串
data	由调用者传入[b][b][b][b][b][b][b]的[/b][/b][/b][/b][/b][/b]指针，调用者可以通过该指针向回调函数传入自定义的参数，开发人员应负责此指针所指向内存的释放。[/b]

处理返回数据的回调函数

typedef void(* data_completion_t)(int rc, const char *value, int value_len, const struct Stat *stat, const void *data)

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

rc	异步函数调用返回的错误码，连接丢失/超时将触发该原型函数(此处指具有该函数原型的回调函数，下同)的调用，并且错误码为 ZCONNECTIONLOSS -- Zookeeper 客户端与服务器端的连接丢失，或者 ZOPERATIONTIMEOUT -- 连接超时；而与数据相关的事件也会触发该原型函数的调用，同时置相应的错误码，具体见后文(0 代异步函数调用成功)
value	异步调用的返回值，[b][b]如果返回非 0 值(即异步调用函数出错)，value 所指向的区域是未定义的，开发者不负责释放 [b][b][b]value[/b][/b] 所指向的内存空间。[/b][/b][/b]
value_len	返回 value 数据字节数(bytes)
stat	指向与该 znode 节点相关的 Stat 信息，如果返回非 0 值(即异步调用函数出错)，stat 所指向的区域是未定义的，开发者不负责释放 stat 所指向的内存空间。
data	由调用者传入[b][b][b][b][b][b][b]的[/b][/b][/b][/b][/b][/b]指针，调用者可以通过该指针向回调函数传入自定义的参数，开发人员应负责此指针所指向内存的释放。[/b]

处理返回字符串列表(a list of string)的回调函数

typedef void(* strings_completion_t)(int rc, const struct String_vector *strings, const void *data)

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

rc	异步函数调用返回的错误码，连接丢失/超时将触发该原型函数(此处指具有该函数原型的回调函数，下同)的调用，并且错误码为 ZCONNECTIONLOSS -- Zookeeper 客户端与服务器端的连接丢失，或者 ZOPERATIONTIMEOUT -- 连接超时；而与数据相关的事件也会触发该原型函数的调用，同时置相应的错误码，具体见后文(0 代异步函数调用成功)
strings	指向包含了某 znode 节点的所有子节点名称列表的结构，[b][b][b]如果返回非 0 值(即异步调用函数出错)，strings 所指向的区域是未定义的，开发者不负责释放 [b][b][b]strings[/b][/b] 所指向的内存空间。[/b][/b][/b][/b]
data	由调用者传入[b][b][b][b][b][b][b]的[/b][/b][/b][/b][/b][/b]指针，调用者可以通过该指针向回调函数传入自定义的参数，开发人员应负责此指针所指向内存的释放。[/b]

同时处理返回字符串列表(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)

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

rc	异步函数调用返回的错误码，连接丢失/超时将触发该原型函数(此处指具有该函数原型的回调函数，下同)的调用，并且错误码为 ZCONNECTIONLOSS -- Zookeeper 客户端与服务器端的连接丢失，或者 ZOPERATIONTIMEOUT -- 连接超时；而与数据相关的事件也会触发该原型函数的调用，同时置相应的错误码，具体见后文(0 代异步函数调用成功)
strings	[b]指向包含了某 znode 节点的所有子节点名称列表的结构，[b][b][b]如果返回非 0 值(即异步调用函数出错)，strings 所指向的区域是未定义的，开发者不负责释放 [b][b][b]strings[/b][/b] 所指向的内存空间。[/b][/b][/b][/b][/b]
stat	指向与该 znode 节点相关的 Stat 信息，如果返回非 0 值(即异步调用函数出错)，stat 所指向的区域是未定义的，开发者不负责释放 stat 所指向的内存空间。
data	由调用者传入的指针，调用者可以通过该指针向回调函数传入自定义的参数，开发人员应负责此指针所指向内存的释放。

处理返回 ACL 信息的回调函数

typedef void(* acl_completion_t)(int rc, struct ACL_vector *acl, struct Stat *stat, const void *data)

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

rc	异步函数调用返回的错误码，连接丢失/超时将触发该原型函数(此处指具有该函数原型的回调函数，下同)的调用，并且错误码为 ZCONNECTIONLOSS -- Zookeeper 客户端与服务器端的连接丢失，或者 ZOPERATIONTIMEOUT -- 连接超时；而与数据相关的事件也会触发该原型函数的调用，同时置相应的错误码，具体见后文(0 代异步函数调用成功)
acl	指向包含某 znode 节点 ACL 信息的指针，[b][b][b][b][b]如果返回非 0 值(即异步调用函数出错)，acl 所指向的区域是未定义的，开发者不负责释放 [b][b][b]acl[/b][/b] 所指向的内存空间。[/b][/b][/b][/b][/b][/b]
stat	指向与该 znode 节点相关的 Stat 信息，如果返回非 0 值(即异步调用函数出错)，stat 所指向的区域是未定义的，开发者不负责释放 stat 所指向的内存空间。
data	由调用者传入的指针，调用者可以通过该指针向回调函数传入自定义的参数，开发人员应负责此指针所指向内存的释放。

至此，所有的回调函数均已介绍完毕，下一节将介绍 Zookeeper C API 分类和基本 API 的使用，见第四讲《Zookeeper C API 指南四(C API 概览)》