{"id":17200560,"url":"https://github.com/mark-5/p5-zookeeper","last_synced_at":"2025-03-25T08:42:08.763Z","repository":{"id":29169836,"uuid":"32700413","full_name":"mark-5/p5-zookeeper","owner":"mark-5","description":"Perl bindings for Apache ZooKeeper","archived":false,"fork":false,"pushed_at":"2019-06-17T02:48:00.000Z","size":159,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-30T08:14:25.204Z","etag":null,"topics":["perl"],"latest_commit_sha":null,"homepage":null,"language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mark-5.png","metadata":{"files":{"readme":"README.pod","changelog":"Changes","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-03-22T23:08:54.000Z","updated_at":"2017-05-04T08:25:02.000Z","dependencies_parsed_at":"2022-08-17T19:15:33.641Z","dependency_job_id":null,"html_url":"https://github.com/mark-5/p5-zookeeper","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mark-5%2Fp5-zookeeper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mark-5%2Fp5-zookeeper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mark-5%2Fp5-zookeeper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mark-5%2Fp5-zookeeper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mark-5","download_url":"https://codeload.github.com/mark-5/p5-zookeeper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245431697,"owners_count":20614182,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["perl"],"created_at":"2024-10-15T02:09:02.406Z","updated_at":"2025-03-25T08:42:08.730Z","avatar_url":"https://github.com/mark-5.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"=head1 NAME\n\nZooKeeper - Perl bindings for Apache ZooKeeper\n\n=head1 SYNOPSIS\n\n    my $zk = ZooKeeper-\u003enew(hosts =\u003e 'localhost:2181');\n\n    my $cv = AE::cv;\n    my @children = $zk-\u003eget_children('/', watcher =\u003e sub { my $event = shift; $cv-\u003esend($event) });\n    my $child_event = $cv-\u003erecv;\n\n=head1 STATUS\n\nUnstable.\n\nUntil version 1.0.0, some aspects of the API may change, most likely related to exception handling for commands and watchers.\n\n=head1 DESCRIPTION\n\nZooKeeper is a perl interface to the Apache ZooKeeper C client library.\n\n=head2 How is this different from Net::ZooKeeper?\n\n=over 4\n\n=item ZooKeeper is written for asynchronous programming.\n\nTo support asynchronous programs, watchers were implemented as code refs, which a ZooKeeper::Dispatcher asynchronously invokes with ZooKeeper event data. Conversely, Net::ZooKeeper used Net::ZooKeeper::Watch classes, which users must interact with using the wait method(which blocks).\n\n=item ZooKeeper data is represented as normal perl data types.\n\nZooKeeper event and stat data are simply hashrefs and arrayrefs. Net::ZooKeeper instead provides specific perl classes for interacting with this data.\n\n=item ZooKeeper leverages perl exception handling.\n\nInstead of returning the C error codes, as Net::ZooKeeper does, ZooKeeper throws ZooKeeper::Error exceptions for unexpected return codes.\n\n=back\n\n=head2 Data Types\n\n=over 4\n\n=item acl\n\nAcls are represented as an arrayrefs of hashrefs, where each hashref includes an id, scheme, and permissions. Permissions flags can be imported from the ZooKeeper::Constants package.\n\nFor instance, ZOO_READ_ACL_UNSAFE would be represented as:\n\n    [{id =\u003e 'anyone', scheme =\u003e 'world', perms =\u003e ZOO_PERM_READ}]\n\n=item event\n\nA hashref of attributes for a watcher event. Includes the type of event(a ZooKeeper::Constants event), connection state(a ZooKeeper::Constants state) and the path of the node triggering the event.\n\n    {\n        path  =\u003e '/child',\n        state =\u003e ZOO_CONNECTED_STATE,\n        type  =\u003e ZOO_CHILD_EVENT,\n    }\n\n=item stat\n\nA hashref of fields from a C Stat struct.\n\n    {\n        aversion       =\u003e 0,\n        ctime          =\u003e 0,\n        cversion       =\u003e 0,\n        czxid          =\u003e 0,\n        ephemeralOwner =\u003e 0,\n        dataLength     =\u003e 0,\n        mtime          =\u003e 0,\n        mzxid          =\u003e 0,\n        numChildren    =\u003e 2,\n        pzxid          =\u003e 2334,\n        version        =\u003e 0,\n    }\n\n=back\n\n=head2 Dispatchers\n\nZooKeeper uses ZooKeeper::Dispatchers for communicating with callbacks registered by the C library. These callbacks are executed in separate POSIX threads, which write event data to a ZooKeeper::Channel and notify the dispatcher that an event is ready to be processed. How this notification occurs, and how perl callbacks are invoked, is what differentiates the types of dispatchers.\n\n=over 4\n\n=item AnyEvent\n\nZooKeeper writes to a Unix pipe with an attached AnyEvent I/O watcher. This means that perl callbacks for watchers will be executed by the AnyEvent event loop.\n\n=item Interrupt\n\nZooKeeper uses Async::Interrupt callbacks. This means the perl interpreter will be safely interrupted(waits for the current op to finish) in order to execute the corresponding perl callback. See Async::Interrupt for more details on how callbacks are executed. Be aware that this does not interrupt system calls(such as select) and XS code. This means if your code is blocking on a select(such as during an AnyEvent recv), the interrupt callback will not execute until the call has finished.\n\n=item IOAsync\n\nZooKeeper writes to a Unix pipe with an attached IO::Async::Handle.\n\nThe IO::Async dispatcher requires an IO::Async::Loop, and needs to be constructed manually\n\n    my $loop = IO::Async::Loop-\u003enew;\n    my $disp = ZooKeeper::Dispatcher::IOAsync-\u003enew(loop =\u003e $loop);\n    my $zk = ZooKeeper-\u003enew(\n        hosts      =\u003e 'localhost:2181',\n        dispatcher =\u003e $disp,\n    );\n\n=item Mojo\n\nZooKeeper writes to a Unix pipe with an attached Mojo::Reactor watcher.\n\n=item POE\n\nZooKeeper writes to a Unix pipe with an attached POE::Session.\n\n=back\n\n=head1 ATTRIBUTES\n\n=head2 hosts\n\nA comma separated list of ZooKeeper server hostnames and ports.\n\n    'localhost:2181'\n    'zoo1.domain:2181,zoo2.domain:2181'\n\n\n=cut\n\n=head2 timeout\n\nThe session timout used for the ZooKeeper connection.\n\n\n=cut\n\n=head2 watcher\n\nA subroutine reference to be called by the default watcher for ZooKeeper session events. This attribute is read/write.\n\n\n=cut\n\n=head2 authentication\n\nAn arrayref used for authenticating with ZooKeeper. This will be passed as an array to add_auth.\n\n    [$scheme, $credentials, %extra]\n\n\n=cut\n\n=head2 buffer_length\n\nThe default length of the buffer used for retrieving ZooKeeper data and paths. Defaults to 2048 bytes.\n\n\n=cut\n\n=head2 client_id\n\nThe client_id for a ZooKeeper session. Can be set during construction to resume a previous session.\n\n\n=cut\n\n=head2 default_acl\n\n\n=cut\n\n=head2 dispatcher\n\nThe implementation of ZooKeeper::Dispatcher to be used. Defaults to AnyEvent.\n\nValid types include:\n\n=over 4\n\n=item AnyEvent\n\n=item Interrupt\n\n=item Mojo\n\n=item POE\n\n=back\n\nInstead of a string, a dispatcher object can be passed directly. This is necessary if the dispatcher has required attributes(as is the case for ZooKeeper::Dispatcher::IOAsync).\n\n\n=cut\n\n=head2 ignore_session_events\n\nIf set to false, all watchers will be triggered for session events, such as disconnecting and reconnecting to the ZooKeeper server. This means that watchers can be triggered multiple times, until the watcher event is triggered.\n\nThe default value is true, which will only trigger watchers once, for the watcher event.\n\n\n=cut\n\n=head1 METHODS\n\n=head2 new\n\nInstantiate a new ZooKeeper connection.\n\n    my $zk = ZooKeeper-\u003enew(%args)\n\n        %args\n            REQUIRED hosts\n            OPTIONAL authentication\n            OPTIONAL buffer_length\n            OPTIONAL dispatcher\n            OPTIONAL timeout\n            OPTIONAL watcher\n\n=head2 state\n\nGet the state of the ZooKeeper connection. Returns a state enum from ZooKeeper::Constants.\n\n=head2 wait\n\nCalls wait on the underlying ZooKeeper::Dispatcher.\n\nSynchronously dispatch one event. Returns the event hashref the watcher was called with.\nCan optionally be passed a timeout(specified in seconds), which will cause wait to return undef if it does not complete in the specified time.\n\n    my $event = $zk-\u003ewait($seconds)\n\n    OPTIONAL $seconds\n\n\n=cut\n\n=head2 close\n\nClose a ZooKeeper session.\n\nIf the handle was not created by the current process, a ZOO_CLOSE_OP will NOT be sent to the server. Instead, only the underlying socket will be closed.\n\n=head2 reopen\n\nReopen a ZooKeeper session after forking.\n\nThis creates a new ZooKeeper session, without closing the parent session.\n\n\n=cut\n\n=head2 create\n\nCreate a new node with the given path and data. Returns the path for the newly created node on succes. Otherwise a ZooKeeper::Error is thrown.\n\n    my $created_path = $zk-\u003ecreate($requested_path, %extra);\n\n        REQUIRED $requested_path\n\n        OPTIONAL %extra\n            acl\n            buffer_length\n            ephemeral\n            sequential\n            value\n\n\n=cut\n\n=head2 add_auth\n\nAdd authentication credentials for the session. Will automatically be invoked if the authentication attribute was set during construction.\n\nA ZooKeeper::Error will be thrown if the request could not be made. To determine success or failure authenticating, a watcher must be passed.\n\n    $zk-\u003eadd_auth($scheme, $credentials, %extra)\n\n        REQUIRED $scheme\n        REQUIRED $credentials\n\n        OPTIONAL %extra\n            watcher\n\n\n=cut\n\n=head2 delete\n\nDelete a node at the given path. Throws a ZooKeeper::Error if the delete was unsuccessful.\n\n    $zk-\u003edelete($path, %extra)\n\n        REQUIRED $path\n\n        OPTIONAL %extra\n            version\n\n\n=cut\n\n=head2 ensure_path\n\n\n=cut\n\n=head2 exists\n\nCheck whether a node exists at the given path, and optionally set a watcher for when the node is created or deleted.\nOn success, returns a stat hashref for the node. Otherwise returns undef.\n\n    my $stat = $zk-\u003eexists($path, %extra)\n\n        REQUIRED $path\n\n        OPTIONAL %extra\n            watcher\n\n\n=cut\n\n=head2 get_children\n\nGet the children stored directly under the given path. Optionally set a watcher for when a child is created or deleted.\nReturns an array of child path names.\n\n    my @child_paths = $zk-\u003eget_children($path, %extra)\n\n        REQUIRED $path\n\n        OPTIONAL %extra\n            watcher\n\n\n=cut\n\n=head2 get\n\nRetrieve data stored at the given path. Optionally set a watcher for when the data is changed.\nIn list context, the data and stat hashref of the node is returned. Otherwise just the data is returned.\n\n    my $data          = $zk-\u003eget($path, %extra)\n    my ($data, $stat) = $zk-\u003eget($path, %extra)\n\n        REQUIRED $path\n\n        OPTIONAL %extra\n            watcher\n            buffer_length\n\n\n=cut\n\n=head2 set\n\nSet data at the given path.\nOn succes, returns a stat hashref of the node. Otherwise a ZooKeeper::Error is thrown.\n\n    my $stat = $zk-\u003eset($path =\u003e $value, %extra)\n\n        REQUIRED $path\n        REQUIRED $value\n\n        OPTIONAL %extra\n            version\n\n\n=cut\n\n=head2 get_acl\n\nGet ACLs for the given node.\nReturns an ACLs arrayref on success, otherwise throws a ZooKeeper::Error\n\n    my $acl = $zk-\u003eget_acl($path)\n\n        REQUIRED $path\n\n=head2 set_acl\n\nSet ACls for a node at the given path. Throws a ZooKeeper::Error on failure.\n\n    $zk-\u003eset_acl($path =\u003e $acl, %extra)\n\n        REQUIRED $path\n        REQUIRED $acl\n\n        OPTIONAL %extra\n            version\n\n\n=cut\n\n=head2 transaction\n\nReturn a ZooKeeper::Transaction for atomically updating multiple nodes.\nSee L\u003cZooKeeper::Transaction\u003e for more details on using transactions.\n\n    my $txn = $zk-\u003etransaction\n                 -\u003edelete( '/some-node'    )\n                 -\u003ecreate( '/another-node' )\n    my ($delete_result, $create_result) = $txn-\u003ecommit;\n\n\n=cut\n\n=head2 trace\n\nSet the tracing level for the ZooKeeper client. Can also be set using the PERL_ZOOKEEPER_TRACE environmental variable, where PERL_ZOOKEEPER_TRACE=$level=$file traces to $file with debug level $level.\n\n    $zk-\u003etrace($level, $file)\n\n        REQUIRED $level\n        OPTIONAL $file\n\n\n=cut\n\n=head1 CAVEATS\n\n=head2 Forking\n\nZooKeeper now offers experimental support for forking safely. A child process may use either the close or reopen methods on a handle, after forking, to destroy the previous connection. Since forking in a multithreaded process is usually very dangerous, this library only closes the underlying socket, and removes references to the previous zhandle.\n\n=head2 Signals\n\nMany ZooKeeper recipes(such as in the examples directory), rely on clients properly shutting down to delete ephemeral nodes. Otherwise the ZooKeeper server will wait for the entire duration of the timeout specified by the session, before cleaning up. If you are expecting your program to handle signals(such as SIGINT), make sure the program is properly catching them and exiting. See the examples for more information.\n\n=head1 SEE ALSO\n\nThe Apache ZooKeeper project's home page at\nL\u003chttp://zookeeper.apache.org/\u003e provides a wealth of detail\non how to develop applications using ZooKeeper.\n\n=head1 AUTHOR\n\nMark Flickinger \u003cmaf@cpan.org\u003e\n\n=head1 LICENSE\n\nThis software is licensed under the same terms as Perl itself.\n\n\n=cut\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmark-5%2Fp5-zookeeper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmark-5%2Fp5-zookeeper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmark-5%2Fp5-zookeeper/lists"}