hadoop-zookeeper-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From maha...@apache.org
Subject svn commit: r769079 [1/4] - in /hadoop/zookeeper/trunk: ./ src/contrib/zkperl/ src/contrib/zkperl/build/ src/contrib/zkperl/t/
Date Mon, 27 Apr 2009 18:07:57 GMT
Author: mahadev
Date: Mon Apr 27 18:07:56 2009
New Revision: 769079

URL: http://svn.apache.org/viewvc?rev=769079&view=rev
Log:
ZOOKEEPER-378. perl binding for zookeeper (chris darroch via mahadev)

Added:
    hadoop/zookeeper/trunk/src/contrib/zkperl/
    hadoop/zookeeper/trunk/src/contrib/zkperl/Changes
    hadoop/zookeeper/trunk/src/contrib/zkperl/LICENSE
    hadoop/zookeeper/trunk/src/contrib/zkperl/MANIFEST
    hadoop/zookeeper/trunk/src/contrib/zkperl/Makefile.PL
    hadoop/zookeeper/trunk/src/contrib/zkperl/NOTICE
    hadoop/zookeeper/trunk/src/contrib/zkperl/README
    hadoop/zookeeper/trunk/src/contrib/zkperl/ZooKeeper.pm
    hadoop/zookeeper/trunk/src/contrib/zkperl/ZooKeeper.xs
    hadoop/zookeeper/trunk/src/contrib/zkperl/build/
    hadoop/zookeeper/trunk/src/contrib/zkperl/build.xml
    hadoop/zookeeper/trunk/src/contrib/zkperl/build/check_zk_version.c
    hadoop/zookeeper/trunk/src/contrib/zkperl/build/check_zk_version.h
    hadoop/zookeeper/trunk/src/contrib/zkperl/t/
    hadoop/zookeeper/trunk/src/contrib/zkperl/t/10_invalid.t
    hadoop/zookeeper/trunk/src/contrib/zkperl/t/15_thread.t
    hadoop/zookeeper/trunk/src/contrib/zkperl/t/20_tie.t
    hadoop/zookeeper/trunk/src/contrib/zkperl/t/22_stat_tie.t
    hadoop/zookeeper/trunk/src/contrib/zkperl/t/24_watch_tie.t
    hadoop/zookeeper/trunk/src/contrib/zkperl/t/30_connect.t
    hadoop/zookeeper/trunk/src/contrib/zkperl/t/35_log.t
    hadoop/zookeeper/trunk/src/contrib/zkperl/t/40_basic.t
    hadoop/zookeeper/trunk/src/contrib/zkperl/t/45_class.t
    hadoop/zookeeper/trunk/src/contrib/zkperl/t/50_access.t
    hadoop/zookeeper/trunk/src/contrib/zkperl/t/60_watch.t
    hadoop/zookeeper/trunk/src/contrib/zkperl/t/util.pl
    hadoop/zookeeper/trunk/src/contrib/zkperl/typemap
Modified:
    hadoop/zookeeper/trunk/CHANGES.txt

Modified: hadoop/zookeeper/trunk/CHANGES.txt
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/CHANGES.txt?rev=769079&r1=769078&r2=769079&view=diff
==============================================================================
--- hadoop/zookeeper/trunk/CHANGES.txt (original)
+++ hadoop/zookeeper/trunk/CHANGES.txt Mon Apr 27 18:07:56 2009
@@ -114,6 +114,8 @@
 
   ZOOKEEPER-29. Flexible quorums (flavio via mahadev) 
 
+  ZOOKEEPER-378. perl binding for zookeeper (chris darroch via mahadev)
+
 Release 3.1.0 - 2009-02-06
   
 Non-backward compatible changes:

Added: hadoop/zookeeper/trunk/src/contrib/zkperl/Changes
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/contrib/zkperl/Changes?rev=769079&view=auto
==============================================================================
--- hadoop/zookeeper/trunk/src/contrib/zkperl/Changes (added)
+++ hadoop/zookeeper/trunk/src/contrib/zkperl/Changes Mon Apr 27 18:07:56 2009
@@ -0,0 +1,55 @@
+Net::ZooKeeper - Perl extension for Apache ZooKeeper
+
+Revision history
+================
+
+0.01  Dec 5, 2008
+        - initial version
+
+0.02  Dec 16, 2008
+        - support connection to ZooKeeper and get() method
+
+0.03  Jan 9, 2009
+        - implemented watch mechanism for get()
+
+0.04  Jan 15, 2009
+        - all basic ZooKeeper methods supported
+
+0.05  Jan 21, 2009
+        - converted from T_PTROBJ to T_ZK_HASH with PERL_MAGIC_ext,
+          allows DESTROY() to be called repeatedly
+
+0.06  Jan 27, 2009
+        - converted from attribute accessor methods to inner and outer hashes
+          with PERL_MAGIC_tied
+
+0.07  Jan 29, 2009
+        - all tied hash methods completed
+
+0.08  Jan 30, 2009
+        - simple thread safety enforced with CLONE_SKIP
+
+0.09  Feb 12, 2009
+        - ACL constants
+
+0.10  Feb 18, 2009
+        - ACL support
+
+0.11  Feb 21, 2009
+        - ZooKeeper version check
+
+0.20  Feb 25, 2009
+        - refactored watches as subclass
+
+0.30  Feb 27, 2009
+        - refactored stats as subclass
+
+0.31  Mar 6, 2009
+        - test suite completed
+
+0.32  Mar 25, 2009
+        - initial documentation completed, first public release
+
+0.33  Apr 20, 2009
+	- copyright donated to ASF
+

Added: hadoop/zookeeper/trunk/src/contrib/zkperl/LICENSE
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/contrib/zkperl/LICENSE?rev=769079&view=auto
==============================================================================
--- hadoop/zookeeper/trunk/src/contrib/zkperl/LICENSE (added)
+++ hadoop/zookeeper/trunk/src/contrib/zkperl/LICENSE Mon Apr 27 18:07:56 2009
@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed 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.

Added: hadoop/zookeeper/trunk/src/contrib/zkperl/MANIFEST
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/contrib/zkperl/MANIFEST?rev=769079&view=auto
==============================================================================
--- hadoop/zookeeper/trunk/src/contrib/zkperl/MANIFEST (added)
+++ hadoop/zookeeper/trunk/src/contrib/zkperl/MANIFEST Mon Apr 27 18:07:56 2009
@@ -0,0 +1,22 @@
+Changes
+LICENSE
+Makefile.PL
+MANIFEST
+NOTICE
+README
+typemap
+ZooKeeper.pm
+ZooKeeper.xs
+build/check_zk_version.c
+build/check_zk_version.h
+t/10_invalid.t
+t/15_thread.t
+t/20_tie.t
+t/22_stat_tie.t
+t/24_watch_tie.t
+t/30_connect.t
+t/35_log.t
+t/40_basic.t
+t/45_class.t
+t/50_access.t
+t/60_watch.t

Added: hadoop/zookeeper/trunk/src/contrib/zkperl/Makefile.PL
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/contrib/zkperl/Makefile.PL?rev=769079&view=auto
==============================================================================
--- hadoop/zookeeper/trunk/src/contrib/zkperl/Makefile.PL (added)
+++ hadoop/zookeeper/trunk/src/contrib/zkperl/Makefile.PL Mon Apr 27 18:07:56 2009
@@ -0,0 +1,59 @@
+# Net::ZooKeeper - Perl extension for Apache ZooKeeper
+#
+# 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.
+
+use 5.008_008;
+
+use Config;
+use ExtUtils::MakeMaker;
+use Getopt::Long;
+
+my $zk_inc_path;
+my $zk_lib_path;
+
+GetOptions(
+    'zookeeper-include=s' => \$zk_inc_path,
+    'zookeeper-lib=s' => \$zk_lib_path
+);
+
+$zk_inc_path = defined($zk_inc_path) ? "-I$zk_inc_path " : '';
+$zk_lib_path = defined($zk_lib_path) ? "-L$zk_lib_path " : '';
+
+my $cc = $Config{'cc'};
+my $check_file = 'build/check_zk_version';
+
+my $check_out =
+    qx($cc -c $zk_inc_path -I. -c $check_file.c -o $check_file.o 2>&1);
+
+if ($?) {
+    if ($check_out =~ /zookeeper_version\.h/) {
+        die("Could not determine ZooKeeper version:\n\n$check_out");
+    }
+    else {
+        ## keep in sync with build/check_zk_version.h
+        die("Net::ZooKeeper requires at least ZooKeeper version 3.1.1\n");
+    }
+}
+
+WriteMakefile(
+    'INC'          => "$zk_inc_path-I.",
+    'LIBS'         => [ "$zk_lib_path-lzookeeper_mt" ],
+    'NAME'         => 'Net::ZooKeeper',
+    'VERSION_FROM' => 'ZooKeeper.pm',
+    'clean'        => { 'FILES' => 'build/check_zk_version.o' }
+);
+

Added: hadoop/zookeeper/trunk/src/contrib/zkperl/NOTICE
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/contrib/zkperl/NOTICE?rev=769079&view=auto
==============================================================================
--- hadoop/zookeeper/trunk/src/contrib/zkperl/NOTICE (added)
+++ hadoop/zookeeper/trunk/src/contrib/zkperl/NOTICE Mon Apr 27 18:07:56 2009
@@ -0,0 +1,6 @@
+Net::ZooKeeper - Perl extension for Apache ZooKeeper
+Copyright 2009 The Apache Software Foundation
+
+This product includes software developed at
+The Apache Software Foundation (http://www.apache.org/).
+

Added: hadoop/zookeeper/trunk/src/contrib/zkperl/README
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/contrib/zkperl/README?rev=769079&view=auto
==============================================================================
--- hadoop/zookeeper/trunk/src/contrib/zkperl/README (added)
+++ hadoop/zookeeper/trunk/src/contrib/zkperl/README Mon Apr 27 18:07:56 2009
@@ -0,0 +1,74 @@
+Net::ZooKeeper - Perl extension for Apache ZooKeeper
+====================================================
+
+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.  For details see the ZooKeeper home page at:
+
+http://hadoop.apache.org/zookeeper/
+
+INSTALLATION
+
+To install this module type the following:
+
+    perl Makefile.PL \
+        --zookeeper-include=/path/to/zookeeper/client/include \
+        --zookeeper-lib=/path/to/zookeeper/client/lib
+    make
+    ZK_TEST_HOSTS=host:port,... make test
+    make install
+
+The path supplied to the --zookeeper-include option should
+identify the directory that contains the zookeeper.h and other
+ZooKeeper C include files.
+
+The path supplied to the --zookeeper-lib option should identify
+the directory that contains the libzookeeper_mt library.
+
+When running "make test", if no ZK_TEST_HOSTS environment
+variable is set, many tests will be skipped because no connection
+to a ZooKeeper server is available.  To execute these tests,
+the ZK_TEST_HOSTS variable may be assigned a list of one or more
+ZooKeeper host:port pairs, e.g., "localhost:7100,otherhost:7200".
+
+The ZK_TEST_PATH environment variable, if defined, specifies
+the ZooKeeper path under which all test nodes should be created.
+The tests expect to have full read/write/create/delete/admin
+ZooKeeper permissions under this path.  If no ZK_TEST_PATH
+variable is defined, the root ZooKeeper path ("/") is used.
+
+DEPENDENCIES
+
+Version 3.1.1 of ZooKeeper is required at a minimum.
+
+You may also want to apply some of these additional patches to
+the ZooKeeper C API code:
+
+https://issues.apache.org/jira/browse/ZOOKEEPER-262
+https://issues.apache.org/jira/browse/ZOOKEEPER-318
+
+This module requires that the multi-threaded version of the
+ZooKeeper C API client library be available on your system.
+
+This in turn implies that the POSIX pthread library is available
+as well.
+
+COPYRIGHT AND LICENCE
+
+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.
+

Added: hadoop/zookeeper/trunk/src/contrib/zkperl/ZooKeeper.pm
URL: http://svn.apache.org/viewvc/hadoop/zookeeper/trunk/src/contrib/zkperl/ZooKeeper.pm?rev=769079&view=auto
==============================================================================
--- hadoop/zookeeper/trunk/src/contrib/zkperl/ZooKeeper.pm (added)
+++ hadoop/zookeeper/trunk/src/contrib/zkperl/ZooKeeper.pm Mon Apr 27 18:07:56 2009
@@ -0,0 +1,1258 @@
+# Net::ZooKeeper - Perl extension for Apache ZooKeeper
+#
+# 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.
+
+use 5.008_008;
+
+use strict;
+use warnings;
+
+package Net::ZooKeeper;
+
+require Exporter;
+require XSLoader;
+
+our $VERSION = '0.33';
+
+our @ISA = qw(Exporter);
+
+our %EXPORT_TAGS = (
+    'errors' => [qw(
+        ZOK
+        ZSYSTEMERROR
+        ZRUNTIMEINCONSISTENCY
+        ZDATAINCONSISTENCY
+        ZCONNECTIONLOSS
+        ZMARSHALLINGERROR
+        ZUNIMPLEMENTED
+        ZOPERATIONTIMEOUT
+        ZBADARGUMENTS
+        ZINVALIDSTATE
+        ZAPIERROR
+        ZNONODE
+        ZNOAUTH
+        ZBADVERSION
+        ZNOCHILDRENFOREPHEMERALS
+        ZNODEEXISTS
+        ZNOTEMPTY
+        ZSESSIONEXPIRED
+        ZINVALIDCALLBACK
+        ZINVALIDACL
+        ZAUTHFAILED
+        ZCLOSING
+        ZNOTHING
+    )],
+    'node_flags' => [qw(
+        ZOO_EPHEMERAL
+        ZOO_SEQUENCE
+    )],
+    'acl_perms' => [qw(
+        ZOO_PERM_READ
+        ZOO_PERM_WRITE
+        ZOO_PERM_CREATE
+        ZOO_PERM_DELETE
+        ZOO_PERM_ADMIN
+        ZOO_PERM_ALL
+    )],
+    'acls' => [qw(
+        ZOO_OPEN_ACL_UNSAFE
+        ZOO_READ_ACL_UNSAFE
+        ZOO_CREATOR_ALL_ACL
+    )],
+    'events' => [qw(
+        ZOO_CREATED_EVENT
+        ZOO_DELETED_EVENT
+        ZOO_CHANGED_EVENT
+        ZOO_CHILD_EVENT
+        ZOO_SESSION_EVENT
+        ZOO_NOTWATCHING_EVENT
+    )],
+    'states' => [qw(
+        ZOO_EXPIRED_SESSION_STATE
+        ZOO_AUTH_FAILED_STATE
+        ZOO_CONNECTING_STATE
+        ZOO_ASSOCIATING_STATE
+        ZOO_CONNECTED_STATE
+    )],
+    'log_levels' => [qw(
+        ZOO_LOG_LEVEL_OFF
+        ZOO_LOG_LEVEL_ERROR
+        ZOO_LOG_LEVEL_WARN
+        ZOO_LOG_LEVEL_INFO
+        ZOO_LOG_LEVEL_DEBUG
+    )]
+);
+
+{
+    my %tags;
+
+    push @{$EXPORT_TAGS{'all'}},
+        grep {!$tags{$_}++} @{$EXPORT_TAGS{$_}} foreach (keys(%EXPORT_TAGS));
+}
+
+our @EXPORT_OK = ( @{$EXPORT_TAGS{'all'}} );
+
+XSLoader::load('Net::ZooKeeper', $VERSION);
+
+1;
+
+__END__
+
+=head1 NAME
+
+Net::ZooKeeper - Perl extension for Apache ZooKeeper
+
+=head1 SYNOPSIS
+
+  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');
+
+=head1 DESCRIPTION
+
+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
+C<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 C<create()> calls the ZooKeeper
+C function C<zoo_create()>, C<delete()> calls C<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.
+
+=head2 Internal POSIX Threads
+
+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 C<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 C<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 C<fork()>.
+
+=head2 Signals
+
+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.
+
+=head2 Error Handling
+
+Net::ZooKeeper methods return different values in the case of an
+error depending on their purpose and context.  For example,
+C<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 C<get_error()> method
+may be called to examine the specific error code, if any.
+
+If C<get_error()> returns C<ZOK>, no error has occurred.  If the
+error code is less than C<ZAPIERROR>, it indicates a normal error
+condition reported by the ZooKeeper server, such as C<ZNONODE>
+(node does not exist) or C<ZNODEEXISTS> (node already exists).
+
+If the error code is greater than C<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.
+
+=head2 Access Control
+
+If the ZooKeeper cluster is not configured with C<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,
+C<perms>, C<scheme>, and C<id>.  The C<perms> attribute's value
+should be composed by combining ACL permission flags using the
+bitwise OR operator.  See C<:acl_perms> for a list of the
+available ACL permission flags.
+
+The ACL for a node may be read using the C<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 C<'acl'> option to the C<create()> method,
+and may be updated by passing an ACL array to the C<set_acl()> method.
+
+When a client connects to a ZooKeeper cluster it is automatically
+assigned authentication credentials based on its IP address and
+hostname.  Additional authentication credentials may be added using
+the C<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 C<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 C<scheme> attribute of
+C<'digest'> and an C<id> attribute containing a Base64-encoded
+SHA1 digest of the string C<"$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 C<b64digest()> method of the Digest module
+will not result in digest strings with the "=" suffix characters
+required by ZooKeeper.
+
+=head2 Logging
+
+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 L</Internal POSIX Threads> above).
+
+Net::ZooKeeper therefore does not provide per-connection handle
+attributes related to logging.  The global function
+C<Net::ZooKeeper::set_log_level()> may be used to set the current
+log level.  See C<:log_levels> for a list of the available log
+levels.  The default log level is C<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: $!");  
+
+=head2 Connection Order
+
+ZooKeeper clusters are typically made up of an odd number of
+ZooKeeper servers.  When connecting to such a cluster, the
+C<new()> method should be passed a comma-separated list of
+the hostnames and ports for each of the servers in the cluster,
+e.g., C<'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
+C<Net::ZooKeeper::set_deterministic_conn_order(1)>.  Note,
+however, that this will affect all Net::ZooKeeper object
+handles created by the current process.
+
+=head1 ATTRIBUTES
+
+=head2 Net::ZooKeeper
+
+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;
+
+=over 4
+
+=item hosts
+
+The comma-separated list of ZooKeeper server hostnames and ports
+as passed to the C<new()> method.  Note that by default the
+ZooKeeper C client code will reorder this list before attempting
+to connect for the first time; see L</Connection Order> for details.
+
+This attribute is B<read-only> and may not be modified.
+
+=item 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 C<'session_timeout'>
+option of the C<new()> method; the server will adjust the
+requested timeout value so that it is within a certain range
+of the server's C<tickTime> setting.  See the ZooKeeper
+documentation for details.
+
+Because the actual connection to the ZooKeeper server is
+not made during the C<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 C<exists()>) has succeeded.
+
+This attribute is B<read-only> and may not be modified.
+
+=item 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 C<new()> calls as the value of
+the C<'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 C<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 C<exists()>) has succeeded.
+
+This attribute is B<read-only> and may not be modified.
+
+=item data_read_len
+
+The maximum length of node data that will be returned to
+the caller by the C<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
+C<get()> is 1023 bytes.  This may be changed by setting
+the C<data_read_len> attribute to a different value.
+
+Passing a value for the C<'data_read_len'> option when calling
+the C<get()> method will temporarily override the per-handle
+maximum.
+
+=item path_read_len
+
+The maximum length of a newly created node's path that will
+be returned to the caller by the C<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
+C<create()> is 1023 bytes.  This may be changed by setting
+the C<path_read_len> attribute to a different value.
+
+Passing a value for the C<'path_read_len'> option when calling
+the C<create()> method will temporarily override the current
+value of this attribute.
+
+=item watch_timeout
+
+The C<timeout> attribute value, in milliseconds, inherited by
+all watch objects (of class Net::ZooKeeper::Watch) created by
+calls to the C<watch()> method.  When a watch object's
+C<wait()> method is invoked without a C<'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 C<timeout> attribute.
+
+The default C<timeout> attribute value for all watch objects
+created by the C<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 C<watch()> method.  Previously
+created watch objects will not be affected.
+
+Passing a value for the C<'timeout'> option when calling
+the C<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 C<watch()> method, and the C<timeout> attribute
+and C<wait()> method of the Net::ZooKeeper::Watch class.
+
+=item 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 C<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 C<exists()>,
+C<get_children()>, or C<get()> methods.
+
+This attribute is B<read-only> and may not be modified.
+
+=back
+
+=head2 Net::ZooKeeper::Stat
+
+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 C<stat()> method on a Net::ZooKeeper
+handle object, and may then be passed to any methods which accept
+a C<'stat'> option value, such as C<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 B<read-only>.
+
+=over 4
+
+=item ctime
+
+The creation time of the node in milliseconds since the epoch.
+
+=item mtime
+
+The time of the last modification of the node's data in
+milliseconds since the epoch.
+
+=item data_len
+
+The length of the node's data in bytes.
+
+=item num_children
+
+The number of child nodes beneath of the current node.
+
+=item ephemeral_owner
+
+If the node was created with the C<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 C<ZOO_EPHEMERAL> flag, this attribute is set to zero.
+
+=item 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.
+
+=item 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.
+
+=item 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.
+
+=item czxid
+
+The ZooKeeper transaction ID (ZXID) of the transaction which
+created the node.
+
+=item 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 C<czxid> attribute by the
+C<create()> method.
+
+=item 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 C<czxid>
+attribute by the C<create()> method.
+
+=back
+
+=head2 Net::ZooKeeper::Watch
+
+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 C<watch()> method on a Net::ZooKeeper handle object, and
+may then be passed to any methods which accept a C<'watch'>
+option value, such as C<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.
+
+=over 4
+
+=item timeout
+
+The default timeout value, in milliseconds, for all
+invocations of the C<wait()> method made on the watch object.
+When the C<wait()> method is invoked without a
+C<'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 C<'timeout'> option when calling
+the C<wait()> method will temporarily override the current
+value of this attribute and cause the C<wait()> method to
+use a different timeout period.
+
+When a Net::ZooKeeper handle object's C<watch()> method is
+invoked without a C<'timeout'> option, it returns a newly
+created watch object whose C<timeout> attribute value
+is initialized to the current value of the handle object's
+C<watch_timeout> attribute.  When the C<watch()> method is invoked
+with a C<'timeout'> option, the new watch object's C<timeout>
+attribute value is initialized to the value specified by
+the C<'timeout'> option.
+
+See also the C<wait()> method, and the C<watch_timeout> attribute
+and C<watch()> method of the Net::ZooKeeper class.
+
+=item event
+
+The type of event which triggered the notification, such
+as C<ZOO_CHANGED_EVENT> if the node's data was changed.
+See C<: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
+C<exists()> and C<get()> methods will report events relating
+to the node's data, while watches set through the
+C<get_children()> method will report events relating to the
+creation or deletion of child nodes of the watched node.
+
+This attribute is B<read-only> and may not be modified.
+
+=item state
+
+The state of the Net::ZooKeeper connection at the time of
+the event notification.  See C<:states> for a list of
+the possible connection states.  If zero, no event
+notification has occurred yet.
+
+This attribute is B<read-only> and may not be modified.
+
+=back
+
+=head1 METHODS
+
+=head2 Net::ZooKeeper
+
+The following methods are defined for the Net::ZooKeeper class.
+
+=over 4
+
+=item 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 L</Internal POSIX Threads> and
+L</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 C<DESTROY()> method.  (After calling C<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 C<'session_timeout'> option.  The
+ZooKeeper server adjust the requested timeout value so that
+it is within a certain range of the server's C<tickTime> setting;
+the actual session timeout value will be available as the
+value of the handle's C<session_timeout> attribute after at
+least one method call has succeeded.  See the C<session_timeout>
+attribute for more information.
+
+If no C<'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 C<session_timeout> attribute.
+
+Upon successful connection (i.e., after the success of a method
+which requires communication with the server), the C<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
+C<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 C<session_id>
+attribute value before undefining the old handle object
+and then pass that binary string as the value of the
+C<'session_id'> option to the C<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 C<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.
+
+=item 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 C<ZOK>) if no error occurred,
+otherwise non-zero.  Non-zero values may be compared to
+the error code names exported by the C<:errors> tagset.
+
+See L</Error Handling> for more details.
+
+=item add_auth()
+
+  $zkh->add_auth('digest', "$username:$password");
+
+The C<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 L</Access Control> for additional details.
+
+=item 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 C<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 C<path_read_len>
+attribute.  If the length of the actual path exceeds the
+current value of the C<path_read_len> attribute, the path
+returned by the C<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 C<'path_read_len'> option will
+temporarily override the value of the C<path_read_len>
+attribute for the duration of the C<create()> method.
+
+The flag values available for use with the C<'flags'> option
+are C<ZOO_EPHEMERAL> and C<ZOO_SEQUENCE>; both are
+included in the C<:flags> tagset.  The flags should be
+combined with the bitwise OR operator if more than one
+is required.
+
+The C<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
+C<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 L</Access Control>) using the C<'acl'> option.
+See also the C<:acl_perms> and C<:acls> tagsets for lists
+of the available ACL permission flags and pre-defined ACLs.
+
+=item 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 C<'version'> option is supplied, the node
+will only be deleted if its version number matches the given
+value.  See the C<version> attribute of the Net::ZooKeeper::Stat
+class for details on node version numbering.
+
+=item 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 C<exists()> method is successful
+but the node does not exist, it returns false, and C<get_error()>
+will return C<ZNONODE> until another method is called on the
+handle object.
+
+The C<'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 C<exists()> method
+succeeds.  The stat object must first have been created
+using the C<stat()> method.
+
+The C<'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
+C<watch()> method.  If the watch object was previously
+assigned to receive notifications for another node, it
+will be reassigned even if the C<exists()> method fails.
+
+=item 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 C<get_children()> method is successful
+but there are no child nodes, it returns an empty list, and
+C<get_error()> will return C<ZOK> until another method is called
+on the handle object.
+
+In a scalar context, C<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 C<'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 C<watch()> method.  If the watch object was
+previously assigned to receive notifications for another node,
+it will be reassigned even if the C<get_children()> method fails.
+
+=item 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 C<data_read_len> attribute, the
+string returned by the C<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 C<'data_read_len'> option will
+temporarily override the value of the C<data_read_len>
+attribute for the duration of the C<get()> method.
+
+The C<'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 C<get()> method succeeds.  The stat object
+must first have been created using the C<stat()> method.
+
+The C<'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
+C<watch()> method.  If the watch object was previously
+assigned to receive notifications for another node, it
+will be reassigned even if the C<get()> method fails.
+
+=item 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 C<'version'> option is supplied, the node's
+data will only be updated if its version number matches the
+given value.  See the C<version> attribute of the
+Net::ZooKeeper::Stat class for details on node version numbering.
+
+The C<'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 C<set()> method succeeds.  The stat object
+must first have been created using the C<stat()> method.
+
+=item 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 C<get_acl()> method is successful
+but there are no ACL entries, it returns an empty list, and
+C<get_error()> will return C<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 C<perms>,
+C<scheme>, and C<id> elements.  See the L</Access Control>
+section for additional details, and the
+C<:acl_perms> and C<:acls> tagsets for lists of the
+available ACL permission flags and pre-defined ACLs.
+
+In a scalar context, C<get_acl()> returns the number
+of ACL entries upon success, otherwise undef.
+
+The C<'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 C<get_acl()> method succeeds.  The stat object
+must first have been created using the C<stat()> method.
+
+=item 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  C<perms>, C<scheme>, and C<id> elements
+as described in the L</Access Control> section.
+See also the C<:acl_perms> and C<:acls> tagsets for lists
+of the available ACL permission flags and pre-defined ACLs.
+
+If a value for the C<'version'> option is supplied, the node's
+ACL will only be updated if its version number matches the
+given value.  See the C<version> attribute of the
+Net::ZooKeeper::Stat class for details on node version numbering.
+
+=item stat()
+
+  $stat = $zkh->stat();
+
+Creates a new Net::ZooKeeper::Stat object which may be used
+with the C<'stat'> option of the C<exists()>, C<get()>,
+C<set()>, and C<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.
+
+=item 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 C<exists()>, C<get_children()>, or C<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 C<exists()> and C<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
+C<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 C<exists()>,
+C<get_children()>, or C<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 C<ZOO_SESSION_EVENT>.  See C<wait()> for more information
+regarding the watch object's attribute values after a
+connection error.
+
+A watch object may be reused with another C<exists()>,
+C<get_children()>, or C<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 C<watch()> method is invoked without a C<'timeout'>
+option, it returns a newly created watch object whose C<timeout>
+attribute value is initialized to the current value of the
+Net::ZooKeeper handle object's C<watch_timeout> attribute.
+Otherwise, when the C<watch()> method is invoked with a
+C<'timeout'> option, the new watch object's C<timeout> attribute
+value is initialized to the value specified by the
+C<'timeout'> option.
+
+See also the C<watch_timeout> attribute, and the C<timeout>
+attribute and C<wait()> method of the Net::ZooKeeper::Watch
+class.
+
+=back
+
+=head2 Net::ZooKeeper::Stat
+
+No methods are defined for the Net::ZooKeeper::Stat class.
+
+=head2 Net::ZooKeeper::Watch
+
+Only one method is defined for the Net::ZooKeeper::Watch class.
+
+=over 4
+
+=item 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 C<'watch'> option to a
+Net::ZooKeeper method; methods which accept a C<'watch'> option
+are C<exists()>, C<get_children()>, and C<get()>.
+
+When the C<wait()> method is invoked with a C<'timeout'>
+option, it waits for no more than the number of milliseconds
+specified by the C<'timeout'> option.
+Otherwise, when the C<wait()> method is invoked without a
+C<'timeout'> option, it waits for no more than the timeout
+period specified by the value of the watch object's C<timeout>
+attribute.
+
+The C<wait()> method returns true if an event notification
+was received, otherwise false.  When C<wait()> returns true,
+the C<event> and C<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 C<ZOO_SESSION_EVENT>.
+In this case, the C<state> attribute will report the current
+state of the connection to the ZooKeeper cluster.
+
+See also the C<timeout> attribute, and the C<watch()> method
+and C<watch_timeout> attribute of the Net::ZooKeeper class.
+
+=back
+
+=head1 FUNCTIONS
+
+The following functions have global scope and affect all
+Net::ZooKeeper handle objects.
+
+=over 4
+
+=item set_log_level()
+
+  Net::ZooKeeper::set_log_level($level);
+
+The C<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 C<ZOO_LOG_LEVEL_OFF>
+which disables all logging.
+
+See the L</Logging> section for more details and C<:log_levels>
+for a list of the available log levels.
+
+=item set_deterministic_conn_order()
+
+  Net::ZooKeeper::set_deterministic_conn_order(1);
+
+The C<Net::ZooKeeper::set_deterministic_conn_order()> function
+may be called to indicate whether or not the list of ZooKeeper
+servers passed to the C<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 L</Connection Order> section for more details.
+
+=back
+
+=head1 EXPORTS
+
+Nothing is exported by default.  Various tagsets exist which
+group the tags available for export into different categories:
+
+=over 4
+
+=item :errors
+
+ZooKeeper error codes.  These may be compared to the values
+returned by the C<get_error()> method.
+
+=item :node_flags
+
+The ZooKeeper node flags C<ZOO_EPHEMERAL> and C<ZOO_SEQUENCE>,
+which may be passed in the C<'flags'> option to the C<create()>
+method.  When more than node flag is required they
+should be combined using the bitwise OR operator.
+
+=item :acl_perms
+
+The ZooKeeper ACL permission flags which may be used in
+the value of the C<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 C<ZOO_PERM_READ>,
+C<ZOO_PERM_WRITE>, C<ZOO_PERM_CREATE>, C<ZOO_PERM_DELETE>,
+and C<ZOO_PERM_ADMIN>.  For convenience, C<ZOO_PERM_ALL> is
+defined as the bitwise OR of all of these flags.
+
+=item :acls
+
+Common ZooKeeper ACLs which may be useful.  C<ZOO_OPEN_ACL_UNSAFE>
+specifies a node which is entirely open to all users with no
+restrictions at all.  C<ZOO_READ_ACL_UNSAFE> specifies
+a node which is readable by all users; permissions for other actions
+are not defined in this ACL.  C<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.
+
+=item :events
+
+The ZooKeeper event types which are returned in value of
+the C<event> attribute a Net::ZooKeeper::Watch object after
+an event occurs on a watched node.
+
+=item :states
+
+The ZooKeeper connection states which are returned in value of
+the C<state> attribute of a Net::ZooKeeper::Watch object after
+an event occurs on a watched node.
+
+=item :log_levels
+
+The ZooKeeper log levels which may be passed to the
+C<Net::ZooKeeper::set_log_level()> function.  The available
+log levels are, from least to most verbose, C<ZOO_LOG_LEVEL_OFF>
+(the default), C<ZOO_LOG_LEVEL_ERROR>, C<ZOO_LOG_LEVEL_WARN>,
+C<ZOO_LOG_LEVEL_INFO>, and C<ZOO_LOG_LEVEL_DEBUG>.
+
+=item :all
+
+Everything from all of the above tagsets.
+
+=back
+
+=head1 SEE ALSO
+
+The Apache ZooKeeper project's home page at
+L<http://hadoop.apache.org/zookeeper/> provides a wealth of detail
+on how to develop applications using ZooKeeper.
+
+=head1 AUTHOR
+
+Chris Darroch, E<lt>chrisd@apache.orgE<gt>
+
+=head1 COPYRIGHT AND LICENSE
+
+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.
+
+=cut
+



Mime
View raw message