Giters

tarantool / zookeeper

ZooKeeper client for Tarantool

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

ZooKeeper client for Tarantool

Support level

Warning! There is no warranty for the program, to the extent permitted by applicable law This repository is maintained by the community:

  • We do not check compatibility with current versions of Tarantool
  • The Tarantool team does not process requests for support, new functionality, or bug fixes
  • Feel free to take an issue and make a merge request with a solution

Table of contents

Overview

ZooKeeper is a distributed application for managing and coordinating a large number of hosts across a cluster. It helps maintain objects like configuration information and hierarchical naming space and provides various services, such as distributed synchronization and leader election.

Back to TOC

Installation

Using a package manager (CentOS, Fedora, Debian, Ubuntu):

  • Add a tarantool repository.
  • Install tarantool-zookeeper package.

Using tarantoolctl rocks:

  • Install dependencies:
    • CentOS / Fedora: tarantool-devel, zookeeper-native (full list).
    • Debian / Ubuntu: tarantool-dev, libzookeeper-st-dev, libzookeeper-st2 (full list).
  • tarantoolctl rocks install zookeeper

Back to TOC

API reference

z = zookeeper.init(hosts, timeout, opts)

Create a ZooKeeper instance. No connection is established at this point.

Parameters:

  • hosts - a string of the format: host1:port1,host2:port2,.... Default is 127.0.0.1:2181.

  • timeout - recv_timeout (ZooKeeper session timeout) in seconds. Default is 30000.

  • opts - a Lua table with the following fields:

    • clientid - a Lua table of the format {client_id = <number>, passwd = <string>}. Default is nil.
    • flags - ZooKeeper init flags. Default is 0.
    • reconnect_timeout - time in seconds to wait before reconnecting. Default is 1.
    • default_acl - a default access control list (ACL) to use for all create requests. Must be a zookeeper.acl.ACLList instance. Default is zookeeper.acl.ACLS.OPEN_ACL_UNSAFE.

Back to TOC

err = zookeeper.zerror(errorcode)

Get a string description for a ZooKeeper error code.

Parameters:

Back to TOC

zookeeper.deterministic_conn_order(<boolean>)

Instruct ZooKeeper not to randomly choose a server from the hosts provided, but select them sequentially instead.

Parameters:

  • a boolean specifying whether a deterministic connection order should be enforced

Back to TOC

zookeeper.set_log_level(zookeeper.const.log_level.*)

Set a ZooKeeper logging level.

Parameters:

Back to TOC

ZooKeeper instance methods

z:start()

Start a ZooKeeper I/O loop. Connection is established at this stage.

Back to TOC

z:close()

Destroy a ZooKeeper instance. After this method is called, nothing is operable and zookeeper.init() must be called again.

Back to TOC

z:state()

Return the current ZooKeeper state as a number. Refer to the list of possible values.

Tip: to convert a number to a string name, use zookeeper.const.states_rev[<number>].

Back to TOC

z:is_connected()

Return true when z:state() == zookeeper.const.states.CONNECTED.

Back to TOC

z:wait_connected()

Wait until the value of z:state() becomes CONNECTED.

Back to TOC

z:client_id()

Return a Lua table of the following form:

{
	client_id = <number>, -- current session ID
	passwd = <string> -- password
}

Back to TOC

z:set_watcher(watcher_func, extra_context)

Set a watcher function called on every change in ZooKeeper.

Parameters:

  • watcher_func - a function with the following signature:

    local function global_watcher(z, type, state, path, context)
    print(string.format(
		    'Global watcher. type = %s, state = %s, path = %s',
		    zookeeper.const.watch_types_rev[type],
		    zookeeper.const.states_rev[state],
		    path))
    print('Extra context:', json.encode(context))
end

    where:

    Parameter Description
    z A ZooKeeper instance
    type An event type. Refer to the list of acceptable values.
    state An event state. Refer to the list of acceptable values.
    path A path that specifies where an event occurred
    context A variable passed to z:set_watcher() as the second argument

  • extra_context - a context passed to the watcher function

Back to TOC

z:create(path, value, acl, flags)

Create a ZooKeeper node.

Parameters:

  • path - a string of the format: /path/to/node. /path/to must exist.
  • value - a string value to store in a node (may be nil). Default is nil.
  • acl (a zookeeper.acl.ACLList instance) - an ACL to use. Default is z.default_acl.
  • flags - a combination of numeric zookeeper.const.create_flags.* constants.

Back to TOC

z:ensure_path(path)

Make sure that a path exists.

Parameters:

  • path - a path to check

Back to TOC

z:exists(path, watch)

Make sure that a node (including all the parent nodes) exists.

Parameters:

  • path - a path to check
  • watch (boolean) - specifies whether to include a path to a global watcher

Returns:

  • a boolean indicating if the path exists

  • stat - node statistics of the following form:

    - cversion: 30
  mtime: 1511098164443
  pzxid: 108
  mzxid: 4
  ephemeralOwner: 0
  aversion: 0
  czxid: 4
  dataLength: 0
  numChildren: 2
  ctime: 1511098164443
  version: 0

    where:

    Parameter Description
    cversion The number of changes to the children of this node
    mtime The time in milliseconds from epoch when this node was last modified
    pzxid The zxid of the change that last modified children of this node
    mzxid The zxid of the change that last modified this node
    ephemeralOwner The session ID of the owner of this node if the node is an ephemeral node. If it is not an ephemeral node, it is zero.
    aversion The number of changes to the ACL of this node
    czxid The zxid of the change that caused this node to be created
    dataLength The length of the data field of this node
    numChildren The number of children of this node
    ctime The time in milliseconds from epoch when this node was created
    version The number of changes to the data of this node

  • a ZooKeeper return code. Refer to the list of possible API errors and client errors.

Back to TOC

z:delete(path, version)

Delete a node.

Parameters:

  • path - a path to a node to be deleted
  • version - a number specifying which version to delete. Default is -1, which is all versions.

Returns:

Back to TOC

z:get(path, watch)

Get the value of a node.

Parameters:

  • path - a path to a node that holds a needed value
  • watch (boolean) - specifies whether to include a path to a global watcher

Returns:

  • value - the value of a node
  • stat - node statistics
  • a ZooKeeper return code. Refer to the list of possible API errors and client errors.

Back to TOC

z:set(path, version)

Set the value of a node.

Parameters:

  • path - a path to a node to set a value on
  • version - a number specifying which version to delete. Default is -1 (create a new version).

Returns:

  • a boolean indicating if the path exists
  • stat - node statistics
  • a ZooKeeper return code. Refer to the list of possible API errors and client errors.

Back to TOC

z:get_children(path, watch)

Get a node's children.

Parameters:

  • path - a path to a node to get the children of
  • watch (boolean) - specifies whether to include a path to a global watcher

Returns:

  • an array of strings, each representing a node's child
  • a ZooKeeper return code. Refer to the list of possible API errors and client errors.

Back to TOC

z:get_children2(path, watch)

Get a node's children and statistics.

Parameters:

  • path - a path to a node to get the children of
  • watch (boolean) - specifies whether to include a path to a global watcher

Returns:

  • an array of strings, each representing a node's child
  • stat - node statistics
  • a ZooKeeper return code. Refer to the list of possible API errors and client errors.

Back to TOC

Appendix 1: ZooKeeper constants

zookeeper.const also contains a <key>_rev map for each key that holds a reverse (number-to-name) mapping. For example, zookeeper.const.api_errors_rev looks like this:

Code Error
-118 ZSESSIONMOVED
-117 ZNOTHING
-116 ZCLOSING
-115 ZAUTHFAILED
-114 ZINVALIDACL
-113 ZINVALIDCALLBACK
-112 ZSESSIONEXPIRED
-111 ZNOTEMPTY
-110 ZNODEEXISTS
-108 ZNOCHILDRENFOREPHEMERALS
-103 ZBADVERSION
-102 ZNOAUTH
-101 ZNONODE
-100 ZAPIERROR

Back to TOC

watch_types

Type Code Description
NOTWATCHING -2 Watcher is not set
SESSION -1 Watching for session-related events
CREATED 1 Watching for node creation events
DELETED 2 Watching for node deletion events
CHANGED 3 Watching for node change events
CHILD 4 Watching for child-related events

Back to TOC

errors

Error Code Description
ZINVALIDSTATE -9 Invalid zhandle state
ZBADARGUMENTS -8 Invalid arguments
ZOPERATIONTIMEOUT -7 Operation timeout
ZUNIMPLEMENTED -6 Operation is unimplemented
ZMARSHALLINGERROR -5 Error while marshalling or unmarshalling data
ZCONNECTIONLOSS -4 Connection to the server has been lost
ZRUNTIMEINCONSISTENCY -2 A runtime inconsistency was found
ZSYSTEMERROR -1 System error
ZOK 0 Everything is OK

Back to TOC

api_errors

Error Code Description
ZSESSIONMOVED -118 Session moved to another server, so the operation is ignored
ZNOTHING -117 (not an error) no server responses to process
ZCLOSING -116 ZooKeeper is closing
ZAUTHFAILED -115 Client authentication failed
ZINVALIDACL -114 Invalid ACL specified
ZINVALIDCALLBACK -113 Invalid callback specified
ZSESSIONEXPIRED -112 The session has been expired by the server
ZNOTEMPTY -111 The node has children
ZNODEEXISTS -110 The node already exists
ZNOCHILDRENFOREPHEMERALS -108 Ephemeral nodes may not have children
ZBADVERSION -103 Version conflict
ZNOAUTH -102 Not authenticated
ZNONODE -101 Node does not exist
ZAPIERROR -100 API error
ZOK 0 Everything is OK

Back to TOC

states

State Code Description
AUTH_FAILED -113 Authentication has failed
EXPIRED_SESSION -112 Session has expired
CONNECTING 1 ZooKeeper is connecting
ASSOCIATING 2 Information obtained from ZooKeeper is being associated with the connection
CONNECTED 3 ZooKeeper is connected
READONLY 5 ZooKeeper is in read-only mode, accepting only read requests
NOTCONNECTED 999 ZooKeeper is not connected

Back to TOC

log_level

Name Code Description
ERROR 1 Log error events that might still allow the application to continue running
WARN 2 Log potentially harmful situations
INFO 3 Log informational messages that highlight the progress of the application at coarse-grained level
DEBUG 4 Log fine-grained informational events that are most useful to debug an application

Back to TOC

create_flags

Flag Code Description
EPHEMERAL 1 Create an ephemeral node
SEQUENCE 2 Create a sequence node

Back to TOC

permissions

Permission Code Description
READ 1 Can get data from a node and list its children
WRITE 2 Can set data for a node
DELETE 8 Can delete a child node
ADMIN 16 Can set permissions
ALL 31 Can do all of the above

Back to TOC

Copyright & License

Back to TOC

About

ZooKeeper client for Tarantool

License:BSD 2-Clause "Simplified" License

Languages

Language:C 54.4%Language:Lua 37.1%Language:CMake 6.5%Language:Shell 2.0%