Net::ZooKeeper - Perl extension for Apache ZooKeeper

  use Net::ZooKeeper qw(:node_flags :acls);

  my $zkh = Net::ZooKeeper->new('localhost:7000');

  $zkh->create('/foo', 'bar',
               'flags' => ZOO_EPHEMERAL,
               'acl' => ZOO_OPEN_ACL_UNSAFE) or
    die("unable to create node /foo: " . $zkh->get_error() . "\n");

  print "node /foo has value: " . $zkh->get('/foo') . "\n";

  $zkh->set('/foo', 'baz');

  print "node / has child nodes:\n";
  foreach my $path ($zkh->get_children('/')) {
    print "  /$path\n";
  }

  my $stat = $zkh->stat();
  if ($zkh->exists('/foo', 'stat' => $stat)) {
    print "node /foo has stat info:\n";
    while (my($key,$value) = each(%{$stat})) {
      print "  $key: $value\n";
    }
  }

  foreach my $acl_entry ($zkh->get_acl('/foo')) {
    print "node /foo has ACL entry:\n";
    print "  perms:  $acl_entry->{perms}\n";
    print "  scheme: $acl_entry->{scheme}\n";
    print "  id:     $acl_entry->{id}\n";
  }

  my $watch = $zkh->watch('timeout' => 10000);
  $zkh->exists('/foo', 'watch' => $watch);

  if ($watch->wait()) {
    print "watch triggered on node /foo:\n";
    print "  event: $watch->{event}\n";
    print "  state: $watch->{state}\n";
  }
  else {
    print "watch timed out after 10 seconds\n";
  }

  $zkh->delete('/foo');

Net::ZooKeeper provides a Perl interface to the synchronous C API of Apache ZooKeeper. ZooKeeper is coordination service for distributed applications and is a sub-project of the Apache Hadoop project.

Each connection to ZooKeeper is represented as a handle object of the class Net::ZooKeeper, similar to the manner in which database connections are represented in the DBI module.

To disconnect from ZooKeeper, simply destroy the Net::ZooKeeper handle object by undefining it or by explicitly calling the DESTROY() method.

The methods which may be invoked on Net::ZooKeeper handles correspond to the functions of the synchronous ZooKeeper C API; e.g., the Net::ZooKeeper method create() calls the ZooKeeper C function zoo_create(), delete() calls zoo_delete(), and so forth.

The synchronous API functions wait for a response from the ZooKeeper cluster before returning a result to the caller. Using these functions permits Net::ZooKeeper to provide an interface similar to that of a DBI driver module.

The use of the synchronous ZooKeeper C API still requires that the ZooKeeper C client code create several POSIX threads which run concurrently with the main thread containing the Perl interpreter.

The synchronous API functions are wrappers of the asynchronous functions in the ZooKeeper C API. When a request is made by the caller's thread (i.e., the one with the running Perl interpreter), it is enqueued for delivery at a later time by the ZooKeeper C client code's IO thread. The caller's thread then waits for notification before returning from the synchronous API function.

The IO thread dequeues the request and sends it to the ZooKeeper cluster, while also ensuring that a regular "heartbeat" is maintained with the cluster so that the current session does not time out. When the IO thread receives a response from the ZooKeeper cluster, it enqueues the response for delivery to the client by the second thread of the ZooKeeper client code, the completion thread.

If the caller is using the asynchronous API, the completion thread invokes the appropriate callback function provided by the caller for the given request. In the case of Net::ZooKeeper, it is not viable for the completion thread to invoke a Perl callback function at arbitrary times; this could interfere with the state of the Perl interpreter.

For this reason Net::ZooKeeper uses the synchronous API only. After enqueuing requests the synchronous API functions wait for notification of the corresponding response. The completion thread delivers these notifications, at which point the synchronous functions return to their caller.

Note that the IO and completion threads are POSIX threads, not Perl ithreads. Net::ZooKeeper defined a CLONE_SKIP() function so that if Perl ithreads are spawned while a Net::ZooKeeper connection is active, the Net::ZooKeeper handle objects inherited by the spawned ithread contain undefined values so that they can not be used. Thus each ithread will need to create its own private connections to a ZooKeeper cluster.

Note also that before invoking fork() to spawn a new process, all Net::ZooKeeper handles should be destroyed so that all connections to ZooKeeper are closed and all internal POSIX threads have exited. If a child process needs to communicate with ZooKeeper it should open its own private connections after it is created by fork().

The ZooKeeper C API uses TCP connections to communicate with the ZooKeeper cluster. These connections may generate SIGPIPE signals when they encounter errors, such as when a connection is terminated by a ZooKeeper server. Therefore most applications will want to trap or ignore SIGPIPE signals, e.g.:

  local $SIG{'PIPE'} = 'IGNORE';

Ignoring SIGPIPE signals (or providing a signal handler that returns control to the interrupted program after receiving the signal) will allow the ZooKeeper C client code to detect the connection error and report it upon return from the next Net::ZooKeeper method.

Net::ZooKeeper methods return different values in the case of an error depending on their purpose and context. For example, exists() returns true if the node exists and false otherwise, which may indicate either that the node does not exist or that an error occurred.

After any method returns a false, empty, or undefined value which might indicate an error has occurred, the get_error() method may be called to examine the specific error code, if any.

If get_error() returns ZOK, no error has occurred. If the error code is less than ZAPIERROR, it indicates a normal error condition reported by the ZooKeeper server, such as ZNONODE (node does not exist) or ZNODEEXISTS (node already exists).

If the error code is greater than ZAPIERROR, then a connection error or server error has occurred and the client should probably close the connection by undefining the Net::ZooKeeper handle object and, if necessary, attempt to create a new connection to the ZooKeeper cluster.

If the ZooKeeper cluster is not configured with skipACL=yes then it will respect the access controls set for each node in the ZooKeeper hierarchy. These access controls are defined using ACLs (Access Control Lists); see the ZooKeeper documentation for compete details.

In Net::ZooKeeper, ACLs are represented as arrays of hashes, where each hash is an ACL entry that must contain three attributes, perms, scheme, and id. The perms attribute's value should be composed by combining ACL permission flags using the bitwise OR operator. See :acl_perms for a list of the available ACL permission flags.

The ACL for a node may be read using the get_acl() method. A node's ACL may be set when the node is created by passing an ACL array as the value of the 'acl' option to the create() method, and may be updated by passing an ACL array to the set_acl() method.

When a client connects to a ZooKeeper cluster it is automatically assigned authentication credentials based on its IP address. Additional authentication credentials may be added using the add_auth() method. Once a credential has been added for the current session, there is no way to disable it.

As an example, digest authentication may be enabled for a session by calling add_auth() as follows:

  $zkh->add_auth('digest', "$username:$password");

Note that the username and password are transmitted in cleartext to the ZooKeeper cluster.

Such authentication credentials would enable access to a node whose ACL contained an entry with a scheme attribute of 'digest' and an id attribute containing a Base64-encoded SHA1 digest of the string "$username:$password". The Perl modules Digest and MIME::Base64 may be used to create such ACL ID values as follows:

  use Digest qw();
  use MIME::Base64 qw();

  my $ctx = Digest->new('SHA-1')->add("$username:$password");
  my $digest = MIME::Base64::encode($ctx->digest());

Note that using the b64digest() method of the Digest module will not result in digest strings with the "=" suffix characters required by ZooKeeper.

As of ZooKeeper version 3.1.1, logging in the C client code is implemented with a single, shared file handle to which all of the internal POSIX threads write log messages; by default, this file handle is attached to STDERR.

Moreover, this file handle is shared by all active ZooKeeper connections (each of which has its own private IO and completion threads; see Internal POSIX Threads above).

Net::ZooKeeper therefore does not provide per-connection handle attributes related to logging. The global function Net::ZooKeeper::set_log_level() may be used to set the current log level. See :log_levels for a list of the available log levels. The default log level is ZOO_LOG_LEVEL_OFF.

To capture ZooKeeper log messages to a file instead of STDERR, redirect STDERR to a new file handle in the normal Perl manner:

  open(OLDERR, '>&', fileno(STDERR)) or
    die("unable to dup STDERR: $!");
  open(STDERR, '>', $log_file) or
    die("unable to redirect STDERR: $!");  

ZooKeeper clusters are typically made up of an odd number of ZooKeeper servers. When connecting to such a cluster, the new() method should be passed a comma-separated list of the hostnames and ports for each of the servers in the cluster, e.g., 'host1:7000,host2:7000,host2:7100'.

The default behaviour of the ZooKeeper client code is to reorder this list randomly before making any connections. A connection is then made to the first server in the reordered list. If that connection fails, the IO thread will automatically attempt to reconnect to the cluster, this time to the next server in the list; when the last server in the list is reached, the IO thread will continue again with the first server.

For certain purposes it may be necessary for ZooKeeper clients to know the exact order in which the IO thread will attempt to connect to the servers of a cluster. To do so, call Net::ZooKeeper::set_deterministic_conn_order(1). Note, however, that this will affect all Net::ZooKeeper object handles created by the current process.

The Net::ZooKeeper class provides the main interface to the ZooKeeper client API. The following attributes are available for each Net::ZooKeeper handle object and are specific to that handle and the method calls invoked on it. As with DBI handle objects, attributes may be read and written through a hash interface, e.g.:

  print sprintf("Session timeout is %.2f seconds.\n",
    $zkh->{session_timeout} / 1000);

  $zkh->{watch_timeout} = 10000;

hosts

The comma-separated list of ZooKeeper server hostnames and ports as passed to the new() method. Note that by default the ZooKeeper C client code will reorder this list before attempting to connect for the first time; see Connection Order for details.

This attribute is read-only and may not be modified.

session_timeout

The session timeout value, in milliseconds, as set by the ZooKeeper server after connection. This value may not be exactly the same as what was requested in the 'session_timeout' option of the new() method; the server will adjust the requested timeout value so that it is within a certain range of the server's tickTime setting. See the ZooKeeper documentation for details.

Because the actual connection to the ZooKeeper server is not made during the new() method call but shortly thereafter by the IO thread, note that this value may not be initialized to its final value until at least one other method which requires communication with the server (such as exists()) has succeeded.

This attribute is read-only and may not be modified.

session_id

The client's session ID value as set by the ZooKeeper server after connection. This is a binary data string which may be passed to subsequent new() calls as the value of the 'session_id' option, if the user wishes to attempt to continue a session after a failure. Note that the server may not honour such an attempt.

Because the actual connection to the ZooKeeper server is not made during the new() method call but shortly thereafter by the IO thread, note that this value may not be initialized to its final value until at least one other method which requires communication with the server (such as exists()) has succeeded.

This attribute is read-only and may not be modified.

data_read_len

The maximum length of node data that will be returned to the caller by the get() method. If a node's data exceeds this length, the returned value will be shorter than the actual node data as stored in the ZooKeeper cluster.

The default maximum length of the node data returned by get() is 1023 bytes. This may be changed by setting the data_read_len attribute to a different value.

Passing a value for the 'data_read_len' option when calling the get() method will temporarily override the per-handle maximum.

path_read_len

The maximum length of a newly created node's path that will be returned to the caller by the create() method. If the path of the newly created node exceeds this length, the returned value will be shorter than the actual path of the node as stored in the ZooKeeper cluster.

The default maximum length of the node path returned by create() is 1023 bytes. This may be changed by setting the path_read_len attribute to a different value.

Passing a value for the 'path_read_len' option when calling the create() method will temporarily override the current value of this attribute.

watch_timeout

The timeout attribute value, in milliseconds, inherited by all watch objects (of class Net::ZooKeeper::Watch) created by calls to the watch() method. When a watch object's wait() method is invoked without a 'timeout' option, it waits for an event notification from the ZooKeeper cluster for no longer than the timeout period specified by the value of the watch object's timeout attribute.

The default timeout attribute value for all watch objects created by the watch() method is 1 minute (60000 milliseconds). This may be changed for a particular handle object by setting this attribute to a different value; afterwards, the new value will be inherited by any watch objects created by the handle object's watch() method. Previously created watch objects will not be affected.

Passing a value for the 'timeout' option when calling the watch() method will temporarily override the current value of this attribute and cause the newly created watch object to inherit a different value.

See also the watch() method, and the timeout attribute and wait() method of the Net::ZooKeeper::Watch class.

pending_watches

The number of internal ZooKeeper watches created for this handle object that are still awaiting an event notification from the ZooKeeper cluster.

Note that this number may be different than the number of extant watch objects created by the handle object's watch() method, not only because some event notifications may have occurred, but also if any watch objects have been reassigned by reusing them in more than one call to any of the exists(), get_children(), or get() methods.

This attribute is read-only and may not be modified.

The Net::ZooKeeper::Stat class provides a hash interface to the individual pieces of information which together compose the state of a given ZooKeeper node. Net::ZooKeeper::Stat objects are created by calling the stat() method on a Net::ZooKeeper handle object, and may then be passed to any methods which accept a 'stat' option value, such as exists().

Net::ZooKeeper::Stat objects may be reused multiple times. If the Net::ZooKeeper method to which the stat object is passed succeeds, then the stat object is updated with the newly retrieved node state information, and any state information previously stored in the stat object is overwritten.

All of the attributes of stat objects are read-only.

ctime

The creation time of the node in milliseconds since the epoch.

mtime

The time of the last modification of the node's data in milliseconds since the epoch.

data_len

The length of the node's data in bytes.

num_children

The number of child nodes beneath of the current node.

ephemeral_owner

If the node was created with the ZOO_EPHEMERAL flag, this attribute holds the session ID of the ZooKeeper client which created the node. If the node was not created with the ZOO_EPHEMERAL flag, this attribute is set to zero.

version

The number of revisions of the node's data. The ZooKeeper cluster will increment this version number whenever the node's data is changed. When the node is first created this version number is initialized to zero.

acl_version

The number of revisions of the node's ACL. The ZooKeeper cluster will increment this version number whenever the node's ACL is changed. When the node is first created this version number is initialized to zero.

children_version

The number of revisions of the node's list of child nodes. The ZooKeeper cluster will increment this version number whenever the list of child nodes is changed. When the node is first created this version number is initialized to zero.

czxid

The ZooKeeper transaction ID (ZXID) of the transaction which created the node.

mzxid

The ZooKeeper transaction ID (ZXID) of the transaction which last modified the node's data. This is initially set to the same transaction ID as the czxid attribute by the create() method.

children_zxid

The ZooKeeper transaction ID (ZXID) of the transaction which last modified the node's list of child nodes. This is initially set to the same transaction ID as the czxid attribute by the create() method.

The Net::ZooKeeper::Watch class provides a hash interface to the data returned by event notifications from the ZooKeeper cluster. Net::ZooKeeper::Watch objects are created by calling the watch() method on a Net::ZooKeeper handle object, and may then be passed to any methods which accept a 'watch' option value, such as exists().

Net::ZooKeeper::Watch objects may be reused multiple times. Regardless of whether the Net::ZooKeeper method to which the watch object is passed succeeds, the watch object will be updated to receive an event notification exclusively for the node referenced in that method call. In the case of an error, however, the watch object may never receive any event notification.

timeout

The default timeout value, in milliseconds, for all invocations of the wait() method made on the watch object. When the wait() method is invoked without a 'timeout' option value, it waits for an event notification from the ZooKeeper cluster for no longer than the timeout period specified by this attribute. This default timeout period may be altered by setting this attribute to a different value.

Passing a value for the 'timeout' option when calling the wait() method will temporarily override the current value of this attribute and cause the wait() method to use a different timeout period.

When a Net::ZooKeeper handle object's watch() method is invoked without a 'timeout' option, it returns a newly created watch object whose timeout attribute value is initialized to the current value of the handle object's watch_timeout attribute. When the watch() method is invoked with a 'timeout' option, the new watch object's timeout attribute value is initialized to the value specified by the 'timeout' option.

See also the wait() method, and the watch_timeout attribute and watch() method of the Net::ZooKeeper class.

event

The type of event which triggered the notification, such as ZOO_CHANGED_EVENT if the node's data was changed. See :events for a list of the possible event types. If zero, no event notification has occurred yet.

Note that the events which will trigger a notification will depend on the Net::ZooKeeper method to which the watch object was passed. Watches set through the exists() and get() methods will report events relating to the node's data, while watches set through the get_children() method will report events relating to the creation or deletion of child nodes of the watched node.

This attribute is read-only and may not be modified.

state

The state of the Net::ZooKeeper connection at the time of the event notification. See :states for a list of the possible connection states. If zero, no event notification has occurred yet.

This attribute is read-only and may not be modified.

The following methods are defined for the Net::ZooKeeper class.

new()

  $zkh = Net::ZooKeeper->new('host1:7000,host2:7000');
  $zkh = Net::ZooKeeper->new('host1:7000,host2:7000',
                             'session_timeout' => $session_timeout,
                             'session_id' => $session_id);

Creates a new Net::ZooKeeper handle object and attempts to connect to the one of the servers of the given ZooKeeper cluster. As described in the Internal POSIX Threads and Connection Order sections, the ZooKeeper client code will create an IO thread which maintains the connection with a regular "heartbeat" request. In the event of a connection error the IO thread will also attempt to reconnect to another one of the servers using the same session ID. In general, these actions should be invisible to the user, although Net::ZooKeeper methods may return transient errors while the IO thread reconnects with another server.

To disconnect, undefine the Net::ZooKeeper handle object or call the DESTROY() method. (After calling DESTROY() the handle object can not be reused.)

The ZooKeeper client code will send a "heartbeat" message if a third of the session timeout period has elapsed without any communication with the ZooKeeper server. A specific session timeout period may be requested when creating a Net::ZooKeeper handle object by supplying a value, in milliseconds, for the 'session_timeout' option. The ZooKeeper server adjust the requested timeout value so that it is within a certain range of the server's tickTime setting; the actual session timeout value will be available as the value of the handle's session_timeout attribute after at least one method call has succeeded. See the session_timeout attribute for more information.

If no 'session_timeout' option is provided, the default value of 10 seconds (10000 milliseconds) will be used in the initial connection request; again, the actual timeout period to which the server agrees will be available subsequently as the value of the session_timeout attribute.

Upon successful connection (i.e., after the success of a method which requires communication with the server), the session_id attribute will hold a short binary string which represents the client's session ID as set by the server. All ephemeral nodes created by the session are identified by this ID in the ephemeral_owner attribute of any Net::ZooKeeper::Stat objects used to query their state.

The ZooKeeper client code will use this session ID internally whenever it tries to reconnect to another server in the ZooKeeper cluster after detecting a failed connection. If it successfully reconnects with the same session ID, the session will continue and ephemeral nodes belonging to it will not be deleted.

However, if the server determines that the session has timed out (for example because no "heartbeat" requests have been received within the agreed-upon session timeout period), the session will be terminated by the cluster and all ephemeral nodes owned by the current session automatically deleted.

On occasion the ZooKeeper client code may not be able to quickly reconnect to a live server and the caller may want to destroy the existing Net::ZooKeeper handle object and attempt a fresh connection using the same session ID as before with a new Net::ZooKeeper object. To do so, save the session_id attribute value before undefining the old handle object and then pass that binary string as the value of the 'session_id' option to the new() method when creating the next handle object. After the successful completion of a method which requires communication with the server, if the new handle object's session_id attribute value matches the old session ID then the session has been successfully maintained; otherwise, the old session was expired by the cluster.

get_error()

  $code = $zkh->get_error();

Returns the ZooKeeper error code, if any, from the most recent Net::ZooKeeper method invocation. The returned value will be zero (equivalent to ZOK) if no error occurred, otherwise non-zero. Non-zero values may be compared to the error code names exported by the :errors tagset.

See Error Handling for more details.

add_auth()

  $zkh->add_auth('digest', "$username:$password");

The add_auth() method may be used to add authentication credentials to a session. Once a credential has been added for the current session, there is no way to disable it.

When using the digest authentication scheme, note that the username and password are transmitted in cleartext to the ZooKeeper cluster.

See Access Control for additional details.

create()

  $path = $zkh->create($req_path, $data);
  $path = $zkh->create($req_path, $data,
                       'flags' => (ZOO_EPHEMERAL | ZOO_SEQUENCE),
                       'acl' => ZOO_OPEN_ACL_UNSAFE,
                       'path_read_len' => 100);

Requests that a node be created in the ZooKeeper cluster's hierarchy with the given path and data. Upon success, the returns the node's path, otherwise undef.

The path returned by a successful create() method call may not be the new node's full path as it appears in the ZooKeeper hierarchy, depending on the length of the actual path and the value of the handle object's path_read_len attribute. If the length of the actual path exceeds the current value of the path_read_len attribute, the path returned by the create() method will be truncated; note that the node's path in the ZooKeeper hierarchy is not affected by this truncation.

Specifying a value for the 'path_read_len' option will temporarily override the value of the path_read_len attribute for the duration of the create() method.

The flag values available for use with the 'flags' option are ZOO_EPHEMERAL and ZOO_SEQUENCE; both are included in the :flags tagset. The flags should be combined with the bitwise OR operator if more than one is required.

The ZOO_EPHEMERAL flag causes the node to be marked as ephemeral, meaning it will be automatically deleted if it still exists when the client's session ends. The ZOO_SEQUENCE flag causes a unique integer to be appended to the node's final path component. See the ZooKeeper documentation for additional advice on how to use these flags.

When creating a node it may be important to define an ACL for it; to do this, pass a reference to an ACL array (as described in Access Control) using the 'acl' option. See also the :acl_perms and :acls tagsets for lists of the available ACL permission flags and pre-defined ACLs.

delete()

  $ret = $zkh->delete($path);
  $ret = $zkh->delete($path, 'version' => $version);

Requests that a node be deleted from the ZooKeeper hierarchy. Returns true upon success, false otherwise.

If a value for the 'version' option is supplied, the node will only be deleted if its version number matches the given value. See the version attribute of the Net::ZooKeeper::Stat class for details on node version numbering.

exists()

  $ret = $zkh->exists($path);
  $ret = $zkh->exists($path, 'stat' => $stat, 'watch' => $watch);

Tests whether a given node exists. Returns true if the node exists, otherwise false. When the exists() method is successful but the node does not exist, it returns false, and get_error() will return ZNONODE until another method is called on the handle object.

The 'stat' option may be used to request that a Net::ZooKeeper::Stat object be updated with the node's current state information. The stat object will only be updated if the node exists and the exists() method succeeds. The stat object must first have been created using the stat() method.

The 'watch' option may be used to request that a Net::ZooKeeper::Watch object be assigned to receive notification of an event which alters the node's data. The watch object must first have been created using the watch() method. If the watch object was previously assigned to receive notifications for another node, it will be reassigned even if the exists() method fails.

get_children()

  @child_names  = $zkh->get_children($path);
  $num_children = $zkh->get_children($path, 'watch' => $watch);

Queries the names or number of the child nodes stored beneath a given node in the ZooKeeper hierarchy. In a list context, returns a list of the child nodes' names upon success, otherwise an empty list. When the get_children() method is successful but there are no child nodes, it returns an empty list, and get_error() will return ZOK until another method is called on the handle object.

In a scalar context, get_children() returns the number of child nodes upon success, otherwise undef.

The names of the child nodes are simply the final component of the nodes' paths, i.e., the portion of their path which follows the path of the given parent node, excluding the "/" delimiter.

The 'watch' option may be used to request that a Net::ZooKeeper::Watch object be assigned to receive notification of an event which alters the node's list of child nodes. The watch object must first have been created using the watch() method. If the watch object was previously assigned to receive notifications for another node, it will be reassigned even if the get_children() method fails.

get()

  $data = $zkh->get($path);
  $data = $zkh->get($path, 'data_read_len' => 100,
                    'stat' => $stat, 'watch' => $watch);

Queries the data stored in a given node. Returns the data as a string upon success, otherwise undef. Note that the data may contain nulls if the node's data is not a text string.

If the length of the node's data exceeds the current value of the handle object's data_read_len attribute, the string returned by the get() method will be truncated; note that the node's data in the ZooKeeper cluster is not affected by this truncation.

Specifying a value for the 'data_read_len' option will temporarily override the value of the data_read_len attribute for the duration of the get() method.

The 'stat' option may be used to request that a Net::ZooKeeper::Stat object be updated with the node's current state information. The stat object will only be updated if the get() method succeeds. The stat object must first have been created using the stat() method.

The 'watch' option may be used to request that a Net::ZooKeeper::Watch object be assigned to receive notification of an event which alters the node's data. The watch object must first have been created using the watch() method. If the watch object was previously assigned to receive notifications for another node, it will be reassigned even if the get() method fails.

set()

  $ret = $zkh->set($path, $data);
  $ret = $zkh->set($path, $data, 'version' => $version,
                   'stat' => $stat);

Requests that a node's data be updated in the ZooKeeper hierarchy. Returns true upon success, false otherwise.

If a value for the 'version' option is supplied, the node's data will only be updated if its version number matches the given value. See the version attribute of the Net::ZooKeeper::Stat class for details on node version numbering.

The 'stat' option may be used to request that a Net::ZooKeeper::Stat object be updated with the node's current state information. The stat object will only be updated if the set() method succeeds. The stat object must first have been created using the stat() method.

get_acl()

  @acl = $zkh->get_acl($path);
  $num_acl_entries = $zkh->get_acl($path, 'stat' => $stat);

Queries the ACL associated with a node in the ZooKeeper hierarchy, if any. In a list context, returns an array with the node's ACL entries upon success, otherwise an empty list. When the get_acl() method is successful but there are no ACL entries, it returns an empty list, and get_error() will return ZOK until another method is called on the handle object.

The elements of the returned array are hashes, each of which represents one ACL entry. Each hash contains perms, scheme, and id elements. See the Access Control section for additional details, and the :acl_perms and :acls tagsets for lists of the available ACL permission flags and pre-defined ACLs.

In a scalar context, get_acl() returns the number of ACL entries upon success, otherwise undef.

The 'stat' option may be used to request that a Net::ZooKeeper::Stat object be updated with the node's current state information. The stat object will only be updated if the get_acl() method succeeds. The stat object must first have been created using the stat() method.

set_acl()

  $acl = [{
    'perms' => (ZOO_PERM_READ | ZOO_PERM_WRITE),
    'scheme' => 'digest',
    'id' => "$username:$digest"
  }];
  $ret = $zkh->set_acl($path, $acl);
  $ret = $zkh->set_acl($path, ZOO_OPEN_ACL_UNSAFE,
                       'version' => $version);

Requests that a node's ACL be updated in the ZooKeeper hierarchy. Returns true upon success, false otherwise.

The ACL should be passed as a reference to an array of hashes, where each hash represents one ACL entry. Each hash should contain perms, scheme, and id elements as described in the Access Control section. See also the :acl_perms and :acls tagsets for lists of the available ACL permission flags and pre-defined ACLs.

If a value for the 'version' option is supplied, the node's ACL will only be updated if its version number matches the given value. See the version attribute of the Net::ZooKeeper::Stat class for details on node version numbering.

stat()

  $stat = $zkh->stat();

Creates a new Net::ZooKeeper::Stat object which may be used with the 'stat' option of the exists(), get(), set(), and get_acl() methods. When the stat object is passed to any of these methods, upon success its attribute values are updated to reflect the current state of the node specified in the method call. The stat object is not updated if the method call does not succeed.

watch()

  $watch = $zkh->watch();
  $watch = $zkh->watch('timeout' => $timeout);

Creates a new Net::ZooKeeper::Watch object which may be used to wait for event notifications from the ZooKeeper cluster. Each time the watch object is passed to any of the exists(), get_children(), or get() methods, its attribute values are immediately reset to zero, and will later be updated upon receipt of an appropriate event notification for the node specified in the method call.

The specific types of events which cause notifications to be sent by the ZooKeeper cluster depend on the method call used. After use with the exists() and get() methods, the watch object will be set to receive an event notification caused by a modification of the node's data or the node itself (e.g., deletion of the node). After use with the get_children() method, the watch object will be set to receive an event notification caused by a modification of the node's list of child nodes.

Watch objects receive at most one event notification after their assignment to a node by one of the exists(), get_children(), or get() methods. Note that in the case of an error, the watch object may never receive any event notification. However, when the parent Net::ZooKeeper handle object experiences a connection error, the ZooKeeper client code will notify all pending watches with an event of type ZOO_SESSION_EVENT. See wait() for more information regarding the watch object's attribute values after a connection error.

A watch object may be reused with another exists(), get_children(), or get() method call at any time, in which case the watch object's attribute values are reset to zero and the watch object will no longer be updated by any event notification relevant to the previous method call.

When the watch() method is invoked without a 'timeout' option, it returns a newly created watch object whose timeout attribute value is initialized to the current value of the Net::ZooKeeper handle object's watch_timeout attribute. Otherwise, when the watch() method is invoked with a 'timeout' option, the new watch object's timeout attribute value is initialized to the value specified by the 'timeout' option.

See also the watch_timeout attribute, and the timeout attribute and wait() method of the Net::ZooKeeper::Watch class.

No methods are defined for the Net::ZooKeeper::Stat class.

Only one method is defined for the Net::ZooKeeper::Watch class.

wait()

  $ret = $watch->wait();
  $ret = $watch->wait('timeout' => $timeout);

Waits for an event notification from the ZooKeeper cluster for the node most recently associated with the watch object. Nodes are associated with a watch object by passing the watch object as the value of a 'watch' option to a Net::ZooKeeper method; methods which accept a 'watch' option are exists(), get_children(), and get().

When the wait() method is invoked with a 'timeout' option, it waits for no more than the number of milliseconds specified by the 'timeout' option. Otherwise, when the wait() method is invoked without a 'timeout' option, it waits for no more than the timeout period specified by the value of the watch object's timeout attribute.

The wait() method returns true if an event notification was received, otherwise false. When wait() returns true, the event and state attributes of the watch object will be updated with the event's type and the current connection state.

When the parent Net::ZooKeeper handle object experiences a connection error, the ZooKeeper client code will notify all pending watches with an event of type ZOO_SESSION_EVENT. In this case, the state attribute will report the current state of the connection to the ZooKeeper cluster.

See also the timeout attribute, and the watch() method and watch_timeout attribute of the Net::ZooKeeper class.

The following functions have global scope and affect all Net::ZooKeeper handle objects.

set_log_level()

  Net::ZooKeeper::set_log_level($level);

The Net::ZooKeeper::set_log_level() function may be called to alter the number and type of messages written to the current log file handle (if any). The default value is ZOO_LOG_LEVEL_OFF which disables all logging.

See the Logging section for more details and :log_levels for a list of the available log levels.

set_deterministic_conn_order()

  Net::ZooKeeper::set_deterministic_conn_order(1);

The Net::ZooKeeper::set_deterministic_conn_order() function may be called to indicate whether or not the list of ZooKeeper servers passed to the new() method should be randomly permuted. If set to a true value, the list of servers will not be altered. The default false value indicates the list of servers will be randomly reordered prior to connection.

See the Connection Order section for more details.

Nothing is exported by default. Various tagsets exist which group the tags available for export into different categories:

:errors

ZooKeeper error codes. These may be compared to the values returned by the get_error() method.

:node_flags

The ZooKeeper node flags ZOO_EPHEMERAL and ZOO_SEQUENCE, which may be passed in the 'flags' option to the create() method. When more than node flag is required they should be combined using the bitwise OR operator.

:acl_perms

The ZooKeeper ACL permission flags which may be used in the value of the perms attribute of an ACL entry hash. When more than one ACL permission flag is required they should be combined using the bitwise OR operator.

The available ACL permission flags are ZOO_PERM_READ, ZOO_PERM_WRITE, ZOO_PERM_CREATE, ZOO_PERM_DELETE, and ZOO_PERM_ADMIN. For convenience, ZOO_PERM_ALL is defined as the bitwise OR of all of these flags.

:acls

Common ZooKeeper ACLs which may be useful. ZOO_OPEN_ACL_UNSAFE specifies a node which is entirely open to all users with no restrictions at all. ZOO_READ_ACL_UNSAFE specifies a node which is readable by all users; permissions for other actions are not defined in this ACL. ZOO_CREATOR_ALL_ACL specifies a node for which all actions require the same authentication credentials as held by the session which created the node; this implies that a session should authenticate with an appropriate scheme before creating a node with this ACL.

:events

The ZooKeeper event types which are returned in value of the event attribute a Net::ZooKeeper::Watch object after an event occurs on a watched node.

:states

The ZooKeeper connection states which are returned in value of the state attribute of a Net::ZooKeeper::Watch object after an event occurs on a watched node.

:log_levels

The ZooKeeper log levels which may be passed to the Net::ZooKeeper::set_log_level() function. The available log levels are, from least to most verbose, ZOO_LOG_LEVEL_OFF (the default), ZOO_LOG_LEVEL_ERROR, ZOO_LOG_LEVEL_WARN, ZOO_LOG_LEVEL_INFO, and ZOO_LOG_LEVEL_DEBUG.

:all

Everything from all of the above tagsets.

The Apache ZooKeeper project's home page at http://hadoop.apache.org/zookeeper/ provides a wealth of detail on how to develop applications using ZooKeeper.

Chris Darroch, <chrisd@apache.org>

Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.