include/zookeeper.h File Reference

ZooKeeper functions and definitions. More...

Include dependency graph for zookeeper.h:

Go to the source code of this file.

Data Structures

struct  clientid_t
 client id structure. More...

Defines

#define ZOOAPI
#define ZOK   0
#define ZSYSTEMERROR   -1
#define ZRUNTIMEINCONSISTENCY   (ZSYSTEMERROR - 1)
#define ZDATAINCONSISTENCY   (ZSYSTEMERROR - 2)
#define ZCONNECTIONLOSS   (ZSYSTEMERROR - 3)
#define ZMARSHALLINGERROR   (ZSYSTEMERROR - 4)
#define ZUNIMPLEMENTED   (ZSYSTEMERROR - 5)
#define ZOPERATIONTIMEOUT   (ZSYSTEMERROR - 6)
#define ZBADARGUMENTS   (ZSYSTEMERROR - 7)
#define ZINVALIDSTATE   (ZSYSTEMERROR - 8)
#define ZAPIERROR   -100
#define ZNONODE   (ZAPIERROR - 1)
#define ZNOAUTH   (ZAPIERROR - 2)
#define ZBADVERSION   (ZAPIERROR - 3)
#define ZNOCHILDRENFOREPHEMERALS   (ZAPIERROR - 8)
#define ZNODEEXISTS   (ZAPIERROR - 10)
#define ZNOTEMPTY   (ZAPIERROR - 11)
#define ZSESSIONEXPIRED   (ZAPIERROR - 12)
#define ZINVALIDCALLBACK   (ZAPIERROR - 13)
#define ZINVALIDACL   (ZAPIERROR - 14)
#define ZAUTHFAILED   (ZAPIERROR - 15)
#define ZCLOSING   (ZAPIERROR - 16)
#define ZNOTHING   (ZAPIERROR - 17)

Typedefs

typedef struct _zhandle zhandle_t
 ZooKeeper handle.
typedef void(* watcher_fn )(zhandle_t *, int type, int state, const char *path)
 signature of a watch function.
typedef void(* void_completion_t )(int rc, const void *data)
 signature of a completion function for a call that returns void.
typedef void(* stat_completion_t )(int rc, const struct Stat *stat, const void *data)
 signature of a completion function that returns a Stat structure.
typedef void(* data_completion_t )(int rc, const char *value, int value_len, const struct Stat *stat, const void *data)
 signature of a completion function that returns data.
typedef void(* strings_completion_t )(int rc, const struct String_vector *strings, const void *data)
 signature of a completion function that returns a list of strings.
typedef void(* string_completion_t )(int rc, const char *value, const void *data)
 signature of a completion function that returns a list of strings.
typedef void(* acl_completion_t )(int rc, struct ACL_vector *acl, struct Stat *stat, const void *data)
 signature of a completion function that returns an ACL.

Enumerations

Debug levels
enum  ZooLogLevel { LOG_LEVEL_ERROR = 1, LOG_LEVEL_WARN = 2, LOG_LEVEL_INFO = 3, LOG_LEVEL_DEBUG = 4 }

Functions

ZOOAPI zhandle_tzookeeper_init (const char *host, watcher_fn fn, int recv_timeout, const clientid_t *clientid, void *context, int flags)
 create a handle to used communicate with zookeeper.
ZOOAPI int zookeeper_close (zhandle_t *zh)
 close the zookeeper handle and free up any resources.
ZOOAPI const clientid_tzoo_client_id (zhandle_t *zh)
 return the client session id
ZOOAPI int zoo_recv_timeout (zhandle_t *zh)
ZOOAPI const void * zoo_get_context (zhandle_t *zh)
ZOOAPI void zoo_set_context (zhandle_t *zh, void *context)
ZOOAPI watcher_fn zoo_set_watcher (zhandle_t *zh, watcher_fn newFn)
 set a watcher function
ZOOAPI int zookeeper_interest (zhandle_t *zh, int *fd, int *interest, struct timeval *tv)
 Returns the events that zookeeper is interested in.
ZOOAPI int zookeeper_process (zhandle_t *zh, int events)
 Notifies zookeeper that an event of interest has happened.
ZOOAPI int zoo_state (zhandle_t *zh)
 get the state of the zookeeper connection.
ZOOAPI int zoo_acreate (zhandle_t *zh, const char *path, const char *value, int valuelen, const struct ACL_vector *acl, int flags, string_completion_t completion, const void *data)
 create a node.
ZOOAPI int zoo_adelete (zhandle_t *zh, const char *path, int version, void_completion_t completion, const void *data)
 delete a node in zookeeper.
ZOOAPI int zoo_aexists (zhandle_t *zh, const char *path, int watch, stat_completion_t completion, const void *data)
 checks the existence of a node in zookeeper.
ZOOAPI int zoo_aget (zhandle_t *zh, const char *path, int watch, data_completion_t completion, const void *data)
 gets the data associated with a node.
ZOOAPI int zoo_aset (zhandle_t *zh, const char *path, const char *buffer, int buflen, int version, stat_completion_t completion, const void *data)
 sets the data associated with a node.
ZOOAPI int zoo_aget_children (zhandle_t *zh, const char *path, int watch, strings_completion_t completion, const void *data)
 lists the children of a node.
ZOOAPI int zoo_async (zhandle_t *zh, const char *path, string_completion_t completion, const void *data)
 Flush leader channel.
ZOOAPI int zoo_aget_acl (zhandle_t *zh, const char *path, acl_completion_t completion, const void *data)
 gets the acl associated with a node.
ZOOAPI int zoo_aset_acl (zhandle_t *zh, const char *path, int version, struct ACL_vector *acl, void_completion_t, const void *data)
 sets the acl associated with a node.
ZOOAPI const char * zerror (int c)
 return an error string.
ZOOAPI int zoo_add_auth (zhandle_t *zh, const char *scheme, const char *cert, int certLen, void_completion_t completion, const void *data)
 specify application credentials.
ZOOAPI int is_unrecoverable (zhandle_t *zh)
 checks if the current zookeeper connection state can't be recovered.
ZOOAPI void zoo_set_debug_level (ZooLogLevel logLevel)
 sets the debugging level for the library
ZOOAPI void zoo_set_log_stream (FILE *logStream)
 sets the stream to be used by the library for logging
ZOOAPI void zoo_deterministic_conn_order (int yesOrNo)
 enable/disable quorum endpoint order randomization
ZOOAPI int zoo_create (zhandle_t *zh, const char *path, const char *value, int valuelen, const struct ACL_vector *acl, int flags, char *realpath, int max_realpath_len)
 create a node synchronously.
ZOOAPI int zoo_delete (zhandle_t *zh, const char *path, int version)
 delete a node in zookeeper synchronously.
ZOOAPI int zoo_exists (zhandle_t *zh, const char *path, int watch, struct Stat *stat)
 checks the existence of a node in zookeeper synchronously.
ZOOAPI int zoo_get (zhandle_t *zh, const char *path, int watch, char *buffer, int *buffer_len, struct Stat *stat)
 gets the data associated with a node synchronously.
ZOOAPI int zoo_set (zhandle_t *zh, const char *path, const char *buffer, int buflen, int version)
 sets the data associated with a node.
ZOOAPI int zoo_get_children (zhandle_t *zh, const char *path, int watch, struct String_vector *strings)
 lists the children of a node synchronously.
ZOOAPI int zoo_get_acl (zhandle_t *zh, const char *path, struct ACL_vector *acl, struct Stat *stat)
 gets the acl associated with a node synchronously.
ZOOAPI int zoo_set_acl (zhandle_t *zh, const char *path, int version, const struct ACL_vector *acl)
 sets the acl associated with a node synchronously.

Variables

ACL Consts
ZOOAPI const int PERM_READ
ZOOAPI const int PERM_WRITE
ZOOAPI const int PERM_CREATE
ZOOAPI const int PERM_DELETE
ZOOAPI const int PERM_ADMIN
ZOOAPI const int PERM_ALL
ZOOAPI struct Id ANYONE_ID_UNSAFE
ZOOAPI struct Id AUTH_IDS
ZOOAPI struct ACL_vector OPEN_ACL_UNSAFE
ZOOAPI struct ACL_vector READ_ACL_UNSAFE
ZOOAPI struct ACL_vector CREATOR_ALL_ACL
Interest Consts
These constants are used to express interest in an event and to indicate to zookeeper which events have occurred. They can be ORed together to express multiple interests. These flags are used in the interest and event parameters of zookeeper_interest and zookeeper_process.

ZOOAPI const int ZOOKEEPER_WRITE
ZOOAPI const int ZOOKEEPER_READ
Create Flags
These flags are used by zoo_create to affect node create. They may be ORed together to combine effects.

ZOOAPI const int EPHEMERAL
ZOOAPI const int SEQUENCE
State Consts
These constants represent the states of a zookeeper connection. They are possible parameters of the watcher callback. If a connection moves from the CONNECTED_STATE to the CONNECTING_STATE, all outstanding watches will be removed.

ZOOAPI const int EXPIRED_SESSION_STATE
ZOOAPI const int AUTH_FAILED_STATE
ZOOAPI const int CONNECTING_STATE
ZOOAPI const int ASSOCIATING_STATE
ZOOAPI const int CONNECTED_STATE
Watch Types
These constants indicate the event that caused the watch event. They are possible values of the first parameter of the watcher callback.

ZOOAPI const int CREATED_EVENT
 a node has been created.
ZOOAPI const int DELETED_EVENT
 a node has been deleted.
ZOOAPI const int CHANGED_EVENT
 a node has changed.
ZOOAPI const int CHILD_EVENT
 a change as occurred in the list of children.
ZOOAPI const int SESSION_EVENT
 a session has been lost.
ZOOAPI const int NOTWATCHING_EVENT
 a watch has been removed.


Detailed Description

ZooKeeper functions and definitions.

ZooKeeper is a network service that may be backed by a cluster of synchronized servers. The data in the service is represented as a tree of data nodes. Each node has data, children, an ACL, and status information. The data for a node is read and write in its entirety.

ZooKeeper clients can leave watches when they queries the data or children of a node. If a watch is left, that client will be notified of the change. The notification is a one time trigger. Subsequent chances to the node will not trigger a notification unless the client issues a querity with the watch flag set. If the client is ever disconnected from the service, even if the disconnection is temporary, the watches of the client will be removed from the service, so a client must treat a disconnect notification as an implicit trigger of all outstanding watches.

When a node is created, it may be flagged as an ephemeral node. Ephemeral nodes are automatically removed when a client session is closed or when a session times out due to inactivity (the ZooKeeper runtime fills in periods of inactivity with pings). Ephemeral nodes cannot have children.

ZooKeeper clients are identified by a server assigned session id. For security reasons The server also generates a corresponding password for a session. A client may save its id and corresponding password to persistent storage in order to use the session across program invocation boundaries.


Define Documentation

#define ZOK   0

zookeeper return constants


Typedef Documentation

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

signature of a completion function that returns an ACL.

This method will be invoked at the end of a asynchronous call and also as a result of connection loss or timeout.

Parameters:
rc the error code of the call. Connection loss/timeout triggers the completion with one of the following error codes: ZCONNECTIONLOSS -- lost connection to the server ZOPERATIONTIMEOUT -- connection timed out Data related events trigger the completion with error codes listed the Exceptions section of the documentation of the function that initiated the call. (Zero indicates call was successful.)
acl a pointer to the structure containng the ACL of a node. If a non zero error code is returned, the content of strings is undefined. The programmer is NOT responsible for freeing acl.
stat a pointer to the stat information for the node involved in this function. If a non zero error code is returned, the content of stat is undefined. The programmer is NOT responsible for freeing stat.
data the pointer that was passed by the caller when the function that this completion corresponds to was invoked. The programmer is responsible for any memory freeing associated with the data pointer.

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

signature of a completion function that returns data.

This method will be invoked at the end of a asynchronous call and also as a result of connection loss or timeout.

Parameters:
rc the error code of the call. Connection loss/timeout triggers the completion with one of the following error codes: ZCONNECTIONLOSS -- lost connection to the server ZOPERATIONTIMEOUT -- connection timed out Data related events trigger the completion with error codes listed the Exceptions section of the documentation of the function that initiated the call. (Zero indicates call was successful.)
value the value of the information returned by the asynchronous call. If a non zero error code is returned, the content of value is undefined. The programmer is NOT responsible for freeing value.
value_len the number of bytes in value.
stat a pointer to the stat information for the node involved in this function. If a non zero error code is returned, the content of stat is undefined. The programmer is NOT responsible for freeing stat.
data the pointer that was passed by the caller when the function that this completion corresponds to was invoked. The programmer is responsible for any memory freeing associated with the data pointer.

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

signature of a completion function that returns a Stat structure.

This method will be invoked at the end of a asynchronous call and also as a result of connection loss or timeout.

Parameters:
rc the error code of the call. Connection loss/timeout triggers the completion with one of the following error codes: ZCONNECTIONLOSS -- lost connection to the server ZOPERATIONTIMEOUT -- connection timed out Data related events trigger the completion with error codes listed the Exceptions section of the documentation of the function that initiated the call. (Zero indicates call was successful.)
stat a pointer to the stat information for the node involved in this function. If a non zero error code is returned, the content of stat is undefined. The programmer is NOT responsible for freeing stat.
data the pointer that was passed by the caller when the function that this completion corresponds to was invoked. The programmer is responsible for any memory freeing associated with the data pointer.

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

signature of a completion function that returns a list of strings.

This method will be invoked at the end of a asynchronous call and also as a result of connection loss or timeout.

Parameters:
rc the error code of the call. Connection loss/timeout triggers the completion with one of the following error codes: ZCONNECTIONLOSS -- lost connection to the server ZOPERATIONTIMEOUT -- connection timed out Data related events trigger the completion with error codes listed the Exceptions section of the documentation of the function that initiated the call. (Zero indicates call was successful.)
value the value of the string returned.
data the pointer that was passed by the caller when the function that this completion corresponds to was invoked. The programmer is responsible for any memory freeing associated with the data pointer.

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

signature of a completion function that returns a list of strings.

This method will be invoked at the end of a asynchronous call and also as a result of connection loss or timeout.

Parameters:
rc the error code of the call. Connection loss/timeout triggers the completion with one of the following error codes: ZCONNECTIONLOSS -- lost connection to the server ZOPERATIONTIMEOUT -- connection timed out Data related events trigger the completion with error codes listed the Exceptions section of the documentation of the function that initiated the call. (Zero indicates call was successful.)
strings a pointer to the structure containng the list of strings of the names of the children of a node. If a non zero error code is returned, the content of strings is undefined. The programmer is NOT responsible for freeing strings.
data the pointer that was passed by the caller when the function that this completion corresponds to was invoked. The programmer is responsible for any memory freeing associated with the data pointer.

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

signature of a completion function for a call that returns void.

This method will be invoked at the end of a asynchronous call and also as a result of connection loss or timeout.

Parameters:
rc the error code of the call. Connection loss/timeout triggers the completion with one of the following error codes: ZCONNECTIONLOSS -- lost connection to the server ZOPERATIONTIMEOUT -- connection timed out Data related events trigger the completion with error codes listed the Exceptions section of the documentation of the function that initiated the call. (Zero indicates call was successful.)
data the pointer that was passed by the caller when the function that this completion corresponds to was invoked. The programmer is responsible for any memory freeing associated with the data pointer.

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

signature of a watch function.

Programs wishing to receive events from ZooKeeper need to implement a function with this signature and pass a pointer to the function to zookeeper_init.

typedef struct _zhandle zhandle_t

ZooKeeper handle.

This is the handle that represents a connection to the ZooKeeper service. It is needed to invoke any ZooKeeper function. A handle is obtained using zookeeper_init.


Function Documentation

ZOOAPI int is_unrecoverable ( zhandle_t zh  ) 

checks if the current zookeeper connection state can't be recovered.

The application must close the zhandle and try to reconnect.

Parameters:
zh the zookeeper handle (see zookeeper_init)
Returns:
ZINVALIDSTATE if connection is unrecoverable

ZOOAPI const char* zerror ( int  c  ) 

return an error string.

Parameters:
return code
Returns:
string corresponding to the return code

ZOOAPI int zoo_acreate ( zhandle_t zh,
const char *  path,
const char *  value,
int  valuelen,
const struct ACL_vector *  acl,
int  flags,
string_completion_t  completion,
const void *  data 
)

create a node.

This method will create a node in ZooKeeper. A node can only be created if it does not already exists. The Create Flags affect the creation of nodes. If EPHEMERAL flag is set, the node will automatically get removed if the client session goes away. If the SEQUENCE flag is set, a unique monotonically increasing sequence number is appended to the path name.

Parameters:
zh the zookeeper handle obtained by a call to zookeeper_init
path The name of the node. Expressed as a file name with slashes separating ancestors of the node.
value The data to be stored in the node.
valuelen The number of bytes in data.
acl The initial ACL of the node. If null, the ACL of the parent will be used.
flags this parameter can be set to 0 for normal create or an OR of the Create Flags
completion the routine to invoke when the request completes. The completion will be triggered with one of the following codes passed in as the rc argument: ZOK operation completed succesfully ZNONODE the parent node does not exist. ZNODEEXISTS the node already exists ZNOAUTH the client does not have permission. ZNOCHILDRENFOREPHEMERALS cannot create children of ephemeral nodes.
data The data that will be passed to the completion routine when the function completes.
Returns:
ZOK on success or one of the following errcodes on failure: ZBADARGUMENTS - invalid input parameters ZINVALIDSTATE - zhandle state is either SESSION_EXPIRED_STATE or AUTH_FAILED_STATE ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory

ZOOAPI int zoo_add_auth ( zhandle_t zh,
const char *  scheme,
const char *  cert,
int  certLen,
void_completion_t  completion,
const void *  data 
)

specify application credentials.

The application calls this function to specify its credentials for purposes of authentication. The server will use the security provider specified by the scheme parameter to authenticate the client connection. If the authentication request has failed:

  • the server connection is dropped
  • the watcher is called with the AUTH_FAILED_STATE value as the state parameter.
    Parameters:
    zh the zookeeper handle obtained by a call to zookeeper_init
    scheme the id of authentication scheme. Natively supported: "digest" password-based authentication
    cert application credentials. The actual value depends on the scheme.
    certLen the length of the data parameter
    completion the routine to invoke when the request completes. One of the following result codes may be passed into the completion callback: ZOK operation completed successfully ZAUTHFAILED authentication failed
    data the data that will be passed to the completion routine when the function completes.
    Returns:
    ZOK on success or one of the following errcodes on failure: ZBADARGUMENTS - invalid input parameters ZINVALIDSTATE - zhandle state is either SESSION_EXPIRED_STATE or AUTH_FAILED_STATE ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory ZSYSTEMERROR - a system error occured

ZOOAPI int zoo_adelete ( zhandle_t zh,
const char *  path,
int  version,
void_completion_t  completion,
const void *  data 
)

delete a node in zookeeper.

Parameters:
zh the zookeeper handle obtained by a call to zookeeper_init
path the name of the node. Expressed as a file name with slashes separating ancestors of the node.
version the expected version of the node. The function will fail if the actual version of the node does not match the expected version. If -1 is used the version check will not take place.
completion the routine to invoke when the request completes. The completion will be triggered with one of the following codes passed in as the rc argument: ZOK operation completed succesfully ZNONODE the node does not exist. ZNOAUTH the client does not have permission. ZBADVERSION expected version does not match actual version. ZNOTEMPTY children are present; node cannot be deleted.
data the data that will be passed to the completion routine when the function completes.
Returns:
ZOK on success or one of the following errcodes on failure: ZBADARGUMENTS - invalid input parameters ZINVALIDSTATE - zhandle state is either SESSION_EXPIRED_STATE or AUTH_FAILED_STATE ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory

ZOOAPI int zoo_aexists ( zhandle_t zh,
const char *  path,
int  watch,
stat_completion_t  completion,
const void *  data 
)

checks the existence of a node in zookeeper.

Parameters:
zh the zookeeper handle obtained by a call to zookeeper_init
path the name of the node. Expressed as a file name with slashes separating ancestors of the node.
watch if nonzero, a watch will be set at the server to notify the client if the node changes. The watch will be set even if the node does not exist. This allows clients to watch for nodes to appear.
completion the routine to invoke when the request completes. The completion will be triggered with one of the following codes passed in as the rc argument: ZOK operation completed succesfully ZNONODE the node does not exist. ZNOAUTH the client does not have permission.
data the data that will be passed to the completion routine when the function completes.
Returns:
ZOK on success or one of the following errcodes on failure: ZBADARGUMENTS - invalid input parameters ZINVALIDSTATE - zhandle state is either SESSION_EXPIRED_STATE or AUTH_FAILED_STATE ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory

ZOOAPI int zoo_aget ( zhandle_t zh,
const char *  path,
int  watch,
data_completion_t  completion,
const void *  data 
)

gets the data associated with a node.

Parameters:
zh the zookeeper handle obtained by a call to zookeeper_init
path the name of the node. Expressed as a file name with slashes separating ancestors of the node.
watch if nonzero, a watch will be set at the server to notify the client if the node changes.
completion the routine to invoke when the request completes. The completion will be triggered with one of the following codes passed in as the rc argument: ZOK operation completed succesfully ZNONODE the node does not exist. ZNOAUTH the client does not have permission.
data the data that will be passed to the completion routine when the function completes.
Returns:
ZOK on success or one of the following errcodes on failure: ZBADARGUMENTS - invalid input parameters ZINVALIDSTATE - zhandle state is either in SESSION_EXPIRED_STATE or AUTH_FAILED_STATE ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory

ZOOAPI int zoo_aget_acl ( zhandle_t zh,
const char *  path,
acl_completion_t  completion,
const void *  data 
)

gets the acl associated with a node.

Parameters:
zh the zookeeper handle obtained by a call to zookeeper_init
path the name of the node. Expressed as a file name with slashes separating ancestors of the node.
completion the routine to invoke when the request completes. The completion will be triggered with one of the following codes passed in as the rc argument: ZOK operation completed succesfully ZNONODE the node does not exist. ZNOAUTH the client does not have permission.
data the data that will be passed to the completion routine when the function completes.
Returns:
ZOK on success or one of the following errcodes on failure: ZBADARGUMENTS - invalid input parameters ZINVALIDSTATE - zhandle state is either SESSION_EXPIRED_STATE or AUTH_FAILED_STATE ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory

ZOOAPI int zoo_aget_children ( zhandle_t zh,
const char *  path,
int  watch,
strings_completion_t  completion,
const void *  data 
)

lists the children of a node.

Parameters:
zh the zookeeper handle obtained by a call to zookeeper_init
path the name of the node. Expressed as a file name with slashes separating ancestors of the node.
watch if nonzero, a watch will be set at the server to notify the client if the node changes.
completion the routine to invoke when the request completes. The completion will be triggered with one of the following codes passed in as the rc argument: ZOK operation completed succesfully ZNONODE the node does not exist. ZNOAUTH the client does not have permission.
data the data that will be passed to the completion routine when the function completes.
Returns:
ZOK on success or one of the following errcodes on failure: ZBADARGUMENTS - invalid input parameters ZINVALIDSTATE - zhandle state is either SESSION_EXPIRED_STATE or AUTH_FAILED_STATE ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory

ZOOAPI int zoo_aset ( zhandle_t zh,
const char *  path,
const char *  buffer,
int  buflen,
int  version,
stat_completion_t  completion,
const void *  data 
)

sets the data associated with a node.

Parameters:
zh the zookeeper handle obtained by a call to zookeeper_init
path the name of the node. Expressed as a file name with slashes separating ancestors of the node.
buffer the buffer holding data to be written to the node.
buflen the number of bytes from buffer to write.
version the expected version of the node. The function will fail if the actual version of the node does not match the expected version. If -1 is used the version check will not take place. * completion: If null, the function will execute synchronously. Otherwise, the function will return immediately and invoke the completion routine when the request completes.
completion the routine to invoke when the request completes. The completion will be triggered with one of the following codes passed in as the rc argument: ZOK operation completed succesfully ZNONODE the node does not exist. ZNOAUTH the client does not have permission. ZBADVERSION expected version does not match actual version.
data the data that will be passed to the completion routine when the function completes.
Returns:
ZOK on success or one of the following errcodes on failure: ZBADARGUMENTS - invalid input parameters ZINVALIDSTATE - zhandle state is either SESSION_EXPIRED_STATE or AUTH_FAILED_STATE ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory

ZOOAPI int zoo_aset_acl ( zhandle_t zh,
const char *  path,
int  version,
struct ACL_vector *  acl,
void_completion_t  ,
const void *  data 
)

sets the acl associated with a node.

Parameters:
zh the zookeeper handle obtained by a call to zookeeper_init
path the name of the node. Expressed as a file name with slashes separating ancestors of the node.
buffer the buffer holding the acls to be written to the node.
buflen the number of bytes from buffer to write.
completion the routine to invoke when the request completes. The completion will be triggered with one of the following codes passed in as the rc argument: ZOK operation completed succesfully ZNONODE the node does not exist. ZNOAUTH the client does not have permission. ZINVALIDACL invalid ACL specified ZBADVERSION expected version does not match actual version.
data the data that will be passed to the completion routine when the function completes.
Returns:
ZOK on success or one of the following errcodes on failure: ZBADARGUMENTS - invalid input parameters ZINVALIDSTATE - zhandle state is either SESSION_EXPIRED_STATE or AUTH_FAILED_STATE ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory

ZOOAPI int zoo_async ( zhandle_t zh,
const char *  path,
string_completion_t  completion,
const void *  data 
)

Flush leader channel.

Parameters:
zh the zookeeper handle obtained by a call to zookeeper_init
path the name of the node. Expressed as a file name with slashes separating ancestors of the node.
completion the routine to invoke when the request completes. The completion will be triggered with one of the following codes passed in as the rc argument: ZOK operation completed succesfully ZNONODE the node does not exist. ZNOAUTH the client does not have permission.
data the data that will be passed to the completion routine when the function completes.
Returns:
ZOK on success or one of the following errcodes on failure: ZBADARGUMENTS - invalid input parameters ZINVALIDSTATE - zhandle state is either SESSION_EXPIRED_STATE or AUTH_FAILED_STATE ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory

ZOOAPI int zoo_create ( zhandle_t zh,
const char *  path,
const char *  value,
int  valuelen,
const struct ACL_vector *  acl,
int  flags,
char *  realpath,
int  max_realpath_len 
)

create a node synchronously.

This method will create a node in ZooKeeper. A node can only be created if it does not already exists. The Create Flags affect the creation of nodes. If EPHEMERAL flag is set, the node will automatically get removed if the client session goes away. If the SEQUENCE flag is set, a unique monotonically increasing sequence number is appended to the path name.

Parameters:
zh the zookeeper handle obtained by a call to zookeeper_init
path The name of the node. Expressed as a file name with slashes separating ancestors of the node.
value The data to be stored in the node.
valuelen The number of bytes in data.
acl The initial ACL of the node. If null, the ACL of the parent will be used.
flags this parameter can be set to 0 for normal create or an OR of the Create Flags
realpath the real path that is created (this might be different than the path to create because of the SEQUENCE flag.
the maximum length of real path you would want.
Returns:
one of the following codes are returned: ZOK operation completed succesfully ZNONODE the parent node does not exist. ZNODEEXISTS the node already exists ZNOAUTH the client does not have permission. ZNOCHILDRENFOREPHEMERALS cannot create children of ephemeral nodes. ZBADARGUMENTS - invalid input parameters ZINVALIDSTATE - zhandle state is either SESSION_EXPIRED_STATE or AUTH_FAILED_STATE ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory

ZOOAPI int zoo_delete ( zhandle_t zh,
const char *  path,
int  version 
)

delete a node in zookeeper synchronously.

Parameters:
zh the zookeeper handle obtained by a call to zookeeper_init
path the name of the node. Expressed as a file name with slashes separating ancestors of the node.
version the expected version of the node. The function will fail if the actual version of the node does not match the expected version. If -1 is used the version check will not take place.
Returns:
one of the following values is returned. ZOK operation completed succesfully ZNONODE the node does not exist. ZNOAUTH the client does not have permission. ZBADVERSION expected version does not match actual version. ZNOTEMPTY children are present; node cannot be deleted. ZBADARGUMENTS - invalid input parameters ZINVALIDSTATE - zhandle state is either SESSION_EXPIRED_STATE or AUTH_FAILED_STATE ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory

ZOOAPI void zoo_deterministic_conn_order ( int  yesOrNo  ) 

enable/disable quorum endpoint order randomization

If passed a non-zero value, will make the client connect to quorum peers in the order as specified in the zookeeper_init() call. A zero value causes zookeeper_init() to permute the peer endpoints which is good for more even client connection distribution among the quorum peers.

ZOOAPI int zoo_exists ( zhandle_t zh,
const char *  path,
int  watch,
struct Stat *  stat 
)

checks the existence of a node in zookeeper synchronously.

Parameters:
zh the zookeeper handle obtained by a call to zookeeper_init
path the name of the node. Expressed as a file name with slashes separating ancestors of the node.
watch if nonzero, a watch will be set at the server to notify the client if the node changes. The watch will be set even if the node does not exist. This allows clients to watch for nodes to appear.
the return stat value of the node.
Returns:
return code of the function call. ZOK operation completed succesfully ZNONODE the node does not exist. ZNOAUTH the client does not have permission. ZBADARGUMENTS - invalid input parameters ZINVALIDSTATE - zhandle state is either SESSION_EXPIRED_STATE or AUTH_FAILED_STATE ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory

ZOOAPI int zoo_get ( zhandle_t zh,
const char *  path,
int  watch,
char *  buffer,
int *  buffer_len,
struct Stat *  stat 
)

gets the data associated with a node synchronously.

Parameters:
zh the zookeeper handle obtained by a call to zookeeper_init
path the name of the node. Expressed as a file name with slashes separating ancestors of the node.
watch if nonzero, a watch will be set at the server to notify the client if the node changes.
buffer the buffer holding the node data returned by the server
buffer_len is the size of the buffer pointed to by the buffer parameter. It'll be set to the actual data length upon return.
stat if not NULL, will hold the value of stat for the path on return.
Returns:
return value of the function call. ZOK operation completed succesfully ZNONODE the node does not exist. ZNOAUTH the client does not have permission. ZBADARGUMENTS - invalid input parameters ZINVALIDSTATE - zhandle state is either in SESSION_EXPIRED_STATE or AUTH_FAILED_STATE ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory

ZOOAPI int zoo_get_acl ( zhandle_t zh,
const char *  path,
struct ACL_vector *  acl,
struct Stat *  stat 
)

gets the acl associated with a node synchronously.

Parameters:
zh the zookeeper handle obtained by a call to zookeeper_init
path the name of the node. Expressed as a file name with slashes separating ancestors of the node.
acl the return value of acls on the path.
stat returns the stat of the path specified.
Returns:
the return code for the function call. ZOK operation completed succesfully ZNONODE the node does not exist. ZNOAUTH the client does not have permission. ZBADARGUMENTS - invalid input parameters ZINVALIDSTATE - zhandle state is either SESSION_EXPIRED_STATE or AUTH_FAILED_STATE ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory

ZOOAPI int zoo_get_children ( zhandle_t zh,
const char *  path,
int  watch,
struct String_vector *  strings 
)

lists the children of a node synchronously.

Parameters:
zh the zookeeper handle obtained by a call to zookeeper_init
path the name of the node. Expressed as a file name with slashes separating ancestors of the node.
watch if nonzero, a watch will be set at the server to notify the client if the node changes.
strings return value of children paths.
Returns:
the return code of the function. ZOK operation completed succesfully ZNONODE the node does not exist. ZNOAUTH the client does not have permission. ZBADARGUMENTS - invalid input parameters ZINVALIDSTATE - zhandle state is either SESSION_EXPIRED_STATE or AUTH_FAILED_STATE ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory

ZOOAPI int zoo_set ( zhandle_t zh,
const char *  path,
const char *  buffer,
int  buflen,
int  version 
)

sets the data associated with a node.

Parameters:
zh the zookeeper handle obtained by a call to zookeeper_init
path the name of the node. Expressed as a file name with slashes separating ancestors of the node.
buffer the buffer holding data to be written to the node.
buflen the number of bytes from buffer to write.
version the expected version of the node. The function will fail if the actual version of the node does not match the expected version. If -1 is used the version check will not take place.
Returns:
the return code for the function call. ZOK operation completed succesfully ZNONODE the node does not exist. ZNOAUTH the client does not have permission. ZBADVERSION expected version does not match actual version. ZBADARGUMENTS - invalid input parameters ZINVALIDSTATE - zhandle state is either SESSION_EXPIRED_STATE or AUTH_FAILED_STATE ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory

ZOOAPI int zoo_set_acl ( zhandle_t zh,
const char *  path,
int  version,
const struct ACL_vector *  acl 
)

sets the acl associated with a node synchronously.

Parameters:
zh the zookeeper handle obtained by a call to zookeeper_init
path the name of the node. Expressed as a file name with slashes separating ancestors of the node.
version the expected version of the path.
acl the acl to be set on the path.
Returns:
the return code for the function call. ZOK operation completed succesfully ZNONODE the node does not exist. ZNOAUTH the client does not have permission. ZINVALIDACL invalid ACL specified ZBADVERSION expected version does not match actual version. ZBADARGUMENTS - invalid input parameters ZINVALIDSTATE - zhandle state is either SESSION_EXPIRED_STATE or AUTH_FAILED_STATE ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory

ZOOAPI void zoo_set_log_stream ( FILE *  logStream  ) 

sets the stream to be used by the library for logging

The zookeeper library uses stderr as its default log stream. Application must make sure the stream is writable. Passing in NULL resets the stream to its default value (stderr).

ZOOAPI watcher_fn zoo_set_watcher ( zhandle_t zh,
watcher_fn  newFn 
)

set a watcher function

Returns:
previous watcher function

ZOOAPI int zoo_state ( zhandle_t zh  ) 

get the state of the zookeeper connection.

The return value will be one of the State Consts.

ZOOAPI int zookeeper_close ( zhandle_t zh  ) 

close the zookeeper handle and free up any resources.

After this call, the client session will no longer be valid. The function will flush any outstanding send requests before return. As a result it may block.

This method should only be called only once on a zookeeper handle. Calling twice will cause undefined (and probably undesirable behavior).

Parameters:
zh the zookeeper handle obtained by a call to zookeeper_init
Returns:
a result code. Regardless of the error code returned, the zhandle will be destroyed and all resources freed.
ZOK - success ZBADARGUMENTS - invalid input parameters 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

ZOOAPI zhandle_t* zookeeper_init ( const char *  host,
watcher_fn  fn,
int  recv_timeout,
const clientid_t clientid,
void *  context,
int  flags 
)

create a handle to used communicate with zookeeper.

This method creates a new handle and a zookeeper session that corresponds to that handle.

Parameters:
host the host name to connect to. This may be a comma separated list of different hosts.
fn the watcher callback function. When notifications are triggered this function will be invoked.
clientid the id of a previously established session that this client will be reconnecting to. Pass 0 if not reconnecting to a previous session. If the session timed out or the id is invalid, a new session will be automatically generated. Clients should check the actual session id by calling zoo_client_id.
context the handback object that will be associated with this instance of zhandle_t. Application can access it (for example, in the watcher callback) using zoo_get_context. The object is not used by zookeeper internally and can be null.
flags reserved for future use. Should be set to zero.
Returns:
a pointer to the opaque zhandle structure. If it fails to create a new zhandle the function returns NULL and the errno variable indicates the reason.

ZOOAPI int zookeeper_interest ( zhandle_t zh,
int *  fd,
int *  interest,
struct timeval *  tv 
)

Returns the events that zookeeper is interested in.

Parameters:
zh the zookeeper handle obtained by a call to zookeeper_init
fd is the file descriptor of interest
interest is an or of the ZOOKEEPER_WRITE and ZOOKEEPER_READ flags to indicate the I/O of interest on fd.
tv a timeout value to be used with select/poll system call
Returns:
a result code. ZOK - success ZBADARGUMENTS - invalid input parameters ZINVALIDSTATE - zhandle state is either SESSION_EXPIRED_STATE or AUTH_FAILED_STATE ZCONNECTIONLOSS - a network error occured while attempting to establish a connection to the server ZMARSHALLINGERROR - failed to marshall a request; possibly, out of memory ZOPERATIONTIMEOUT - hasn't received anything from the server for 2/3 of the timeout value specified in zookeeper_init() ZSYSTEMERROR -- a system (OS) error occured; it's worth checking errno to get details

ZOOAPI int zookeeper_process ( zhandle_t zh,
int  events 
)

Notifies zookeeper that an event of interest has happened.

Parameters:
zh the zookeeper handle obtained by a call to zookeeper_init
events will be an OR of the ZOOKEEPER_WRITE and ZOOKEEPER_READ flags.
Returns:
a result code. ZOK - success ZBADARGUMENTS - invalid input parameters ZINVALIDSTATE - zhandle state is either SESSION_EXPIRED_STATE or AUTH_FAILED_STATE ZCONNECTIONLOSS - a network error occured while attempting to send request to server ZSESSIONEXPIRED - connection attempt failed -- the session's expired ZAUTHFAILED - authentication request failed, e.i. invalid credentials ZRUNTIMEINCONSISTENCY - a server response came out of order ZSYSTEMERROR -- a system (OS) error occured; it's worth checking errno to get details ZNOTHING -- not an error; simply indicates that there no more data from the server to be processed (when called with ZOOKEEPER_READ flag).


Variable Documentation

ZOOAPI const int CHANGED_EVENT

a node has changed.

This is only generated by watches on nodes. These watches are set using zoo_exists and zoo_get.

ZOOAPI const int CHILD_EVENT

a change as occurred in the list of children.

This is only generated by watches on the child list of a node. These watches are set using zoo_get_children.

ZOOAPI const int CREATED_EVENT

a node has been created.

This is only generated by watches on non-existent nodes. These watches are set using zoo_exists.

ZOOAPI const int DELETED_EVENT

a node has been deleted.

This is only generated by watches on nodes. These watches are set using zoo_exists and zoo_get.

ZOOAPI const int NOTWATCHING_EVENT

a watch has been removed.

This is generated when the server for some reason, probably a resource constraint, will no longer watch a node for a client.

ZOOAPI const int SESSION_EVENT

a session has been lost.

This is generated when a client loses contact or reconnects with a server.


Generated on Fri May 2 09:14:49 2008 for zookeeper-2.1.0 by  doxygen 1.5.5