GSP
Quick Navigator
Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
ZooKeeper(3) User Contributed Perl Documentation ZooKeeper(3)
 

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.
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. In older ZooKeeper versions(before 3.4.0), these connections may generate SIGPIPE signals when they encounter errors, such as when a connection is terminated by a ZooKeeper server. Therefore applications using older ZooKeeper versions 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.
In order to get a human-readable version of the error code, simply call "str_error()", and it will return a string representing the last encountered error.

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.2.0, 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.
state
The state of the Net::ZooKeeper connection at current time. See ":states" for a list of the possible connection states. If zero, no connection has established yet.
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. On failure, undef will be returned and the error message will be accessible in "$!". 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()".
By default, the "wait()" method will return when session events(such as disconnecting and reconnecting from a server) are triggered. If a watch should ignore these session events, call Net::ZooKeeper::set_ignore_session_events(1).
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.
set_ignore_session_events()
  Net::ZooKeeper::set_ignore_session_events(1);
By default, ZooKeeper will trigger all pending watches for any session event(such as disconnecting and reconnecting to a server). If "Net::ZooKeeper::set_ignore_session_events()" is set to a true value, session events will be ignored and "wait()" calls will only return after the watch event is triggered or times out.

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://zookeeper.apache.org/> provides a wealth of detail on how to develop applications using ZooKeeper.

Chris Darroch, <chrisd@apache.org>
Mark Flickinger, <maf@cpan.org>, is the current co-maintainer

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.
2015-06-18 perl v5.28.1
Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.