Client

Interacting with ZooKeeper as a client. More...

Classes
class	zk::acl_rule
	An individual rule in an acl. More...
class	zk::acl
	An access control list is a wrapper around acl_rule instances. More...
class	zk::acls
	Convenience operations around commonly-used ACLs. More...
class	zk::client
	A ZooKeeper client connection. More...
class	zk::connection
class	zk::connection_params
	Used to specify parameters for a connection. More...
class	zk::connection_zk
class	zk::error
class	zk::system_error
class	zk::runtime_inconsistency
class	zk::data_inconsistency
class	zk::connection_loss
class	zk::marshalling_error
class	zk::unimplemented
class	zk::operation_timeout
class	zk::invalid_arguments
class	zk::invalid_handle_state
class	zk::unknown_session
class	zk::new_configuration_no_quorum
class	zk::reconfiguration_in_progress
class	zk::api_error
class	zk::no_node
class	zk::not_authenticated
class	zk::bad_version
class	zk::no_children_for_ephemerals
class	zk::node_exists
class	zk::not_empty
class	zk::session_expired
class	zk::invalid_callback
class	zk::invalid_acl
class	zk::authentication_failed
class	zk::closing
class	zk::no_response
class	zk::session_moved
class	zk::server_read_only
class	zk::ephemeral_on_local_session
class	zk::no_watcher
class	zk::reconfiguration_disabled
class	zk::transaction_failed
	Thrown from client::commit when a transaction cannot be committed to the system. More...
class	zk::unknown_error
class	zk::op
class	zk::multi_op
class	zk::multi_result
class	zk::get_result
	The result type of client::get. More...
class	zk::get_children_result
	The result type of client::get_children. More...
class	zk::exists_result
	The result type of client::exists. More...
class	zk::create_result
	The result type of client::create. More...
class	zk::set_result
	The result type of client::set. More...
class	zk::get_acl_result
	The result type of client::get_acl. More...
class	zk::event
	Data delivered when a watched event triggers. More...
class	zk::watch_result
	The result type of client::watch. More...
class	zk::watch_children_result
	The result type of client::watch_children. More...
class	zk::watch_exists_result
	The result type of client::watch_exists. More...
struct	zk::strong_id< TReal, TId >
	Base type for creating strong ID types. More...
struct	zk::basic_version< TReal >
	Base type for version types. More...
struct	zk::version
	Represents a version of the data. More...
struct	zk::acl_version
	Represents a version of the ACL of a ZNode. More...
struct	zk::child_version
	Represents a version of the children of a ZNode. More...
struct	zk::transaction_id
struct	zk::stat
	Statistics about a znode, similar to the UNIX stat structure. More...

Macros
#define	ZKPP_BUFFER_USE_CUSTOM   0
	Set this to 1 to use a custom definitions for zk::buffer. More...
#define	ZKPP_BUFFER_USE_STD_VECTOR   1
	Set this to 1 to use std::vector<char> for the implementation of zk::buffer. More...
#define	ZKPP_BUFFER_INCLUDE   <vector>
#define	ZKPP_BUFFER_TYPE   std::vector<char>
#define	ZKPP_VERSION_MAJOR   0
#define	ZKPP_VERSION_MINOR   1
#define	ZKPP_VERSION_PATCH   1
#define	ZKPP_DEBUG   0
	Was ZooKeeper C++ compiled in debug mode? This value must be the same between when the SO was built and when you are compiling. More...
#define	ZKPP_SO   1
	Are you using shared objects (DLLs in Windows)? More...
#define	ZKPP_ERROR_CODE_LIST(item)
#define	ZKPP_ERROR_CODE_SIZE_IMPL(cxx_name, number, c_name)   +1
#define	ZKPP_FUTURE_USE_STD_EXPERIMENTAL   0
	Set this to 1 to use std::experimental::future and std::experimental::promise as the backing types for zk::future and zk::promise. More...
#define	ZKPP_FUTURE_USE_CUSTOM   0
	Set this to 1 to use custom definitions of zk::future and zk::promise. More...
#define	ZKPP_FUTURE_TEMPLATE   std::future
	The template to use for zk::future. More...
#define	ZKPP_PROMISE_TEMPLATE   std::promise
	The template to use for zk::promise. More...
#define	ZKPP_FUTURE_INCLUDE   <future>
	The file to include to get the implementation for future and promise. More...
#define	ZKPP_FUTURE_USE_STD   1
	Set this to 1 to use std::future and std::promise as the backing types for zk::future and zk::promise. More...
#define	ZKPP_OPTIONAL_USE_STD_EXPERIMENTAL   0
	Set this to 1 to use std::experimental::optional, std::experimental::nullopt_t, and std::experimental::nullopt as the backing types for zk::optional, zk::nullopt_t, and zk::nullopt. More...
#define	ZKPP_OPTIONAL_USE_CUSTOM   0
	Set this to 1 to use custom definitions for zk::optional, zk::nullopt_t, and zk::nullopt. More...
#define	ZKPP_OPTIONAL_INCLUDE   <optional>
	The file to include to get the implementation for optional, nullopt_t, and nullopt. More...
#define	ZKPP_OPTIONAL_TEMPLATE   std::optional
	The template to use for zk::optional. More...
#define	ZKPP_NULLOPT_TYPE   std::nullopt_t
	The type to use for zk::nullopt_t. More...
#define	ZKPP_NULLOPT_VALUE   std::nullopt
	The value to use for zk::nullopt. More...
#define	ZKPP_OPTIONAL_USE_STD   1
	Set this to 1 to use std::optional, std::nullopt_t, and std::nullopt as the backing types for zk::optional, zk::nullopt_t, and zk::nullopt. More...
#define	ZKPP_STRING_VIEW_USE_STD_EXPERIMENTAL   0
#define	ZKPP_STRING_VIEW_USE_CUSTOM   0
#define	ZKPP_STRING_VIEW_USE_STD   1
#define	ZKPP_STRING_VIEW_INCLUDE   <string_view>
#define	ZKPP_STRING_VIEW_TYPE   std::string_view

Typedefs
using	zk::buffer = ZKPP_BUFFER_TYPE
	The buffer type. More...
template<typename T >
using	zk::ptr = T *
	A simple, unowned pointer. More...
template<typename T >
using	zk::future = ZKPP_FUTURE_TEMPLATE< T >
template<typename T >
using	zk::promise = ZKPP_PROMISE_TEMPLATE< T >
template<typename T >
using	zk::optional = ZKPP_OPTIONAL_TEMPLATE< T >
using	zk::nullopt_t = ZKPP_NULLOPT_TYPE

Enumerations
enum	zk::permission : unsigned int {   zk::permission::none = 0b00000, zk::permission::read = 0b00001, zk::permission::write = 0b00010, zk::permission::create = 0b00100,   zk::permission::erase = 0b01000, zk::permission::admin = 0b10000, zk::permission::all = 0b11111 }
	Describes the ability of a user to perform a certain action. More...
enum	error_code : int { ZKPP_ERROR_CODE_ENUM_DEF_IMPL }
enum	op_type : int { check, create, erase, set }
enum	zk::create_mode : unsigned int { zk::create_mode::normal = 0b0000, zk::create_mode::ephemeral = 0b0001, zk::create_mode::sequential = 0b0010, zk::create_mode::container = 0b0100 }
	When used in client::set, this value determines how the znode is created on the server. More...
enum	zk::event_type : int {   zk::event_type::error = 0, zk::event_type::created = 1, zk::event_type::erased = 2, zk::event_type::changed = 3,   zk::event_type::child = 4, zk::event_type::session = -1, zk::event_type::not_watching = -2 }
	Enumeration of types of events that may occur. More...
enum	zk::state : int {   zk::state::closed = 0, zk::state::connecting = 1, zk::state::associating = 2, zk::state::connected = 3,   zk::state::read_only = 5, not_connected = 999, zk::state::expired_session = -112, zk::state::authentication_failed = -113 }
	Enumeration of states the client may be at when a watch triggers. More...

Functions
constexpr permission	zk::operator| (permission a, permission b)
constexpr permission	zk::operator& (permission a, permission b)
constexpr permission	zk::operator~ (permission a)
constexpr bool	zk::allows (permission self, permission perform)
	Check that self allows it perform all operations. More...
std::ostream &	zk::operator<< (std::ostream &os, const permission &self)
std::string	zk::to_string (const permission &self)
std::size_t	zk::hash (const acl_rule &self)
bool	zk::operator== (const acl_rule &lhs, const acl_rule &rhs)
bool	zk::operator!= (const acl_rule &lhs, const acl_rule &rhs)
bool	zk::operator< (const acl_rule &lhs, const acl_rule &rhs)
bool	zk::operator<= (const acl_rule &lhs, const acl_rule &rhs)
bool	zk::operator> (const acl_rule &lhs, const acl_rule &rhs)
bool	zk::operator>= (const acl_rule &lhs, const acl_rule &rhs)
std::ostream &	zk::operator<< (std::ostream &os, const acl_rule &self)
std::string	zk::to_string (const acl_rule &self)
bool	zk::operator== (const acl &lhs, const acl &rhs)
bool	zk::operator!= (const acl &lhs, const acl &rhs)
std::ostream &	zk::operator<< (std::ostream &os, const acl &self)
std::string	zk::to_string (const acl &self)
bool	zk::operator== (const connection_params &lhs, const connection_params &rhs)
bool	zk::operator!= (const connection_params &lhs, const connection_params &rhs)
std::string	zk::to_string (const connection_params &x)
std::ostream &	zk::operator<< (std::ostream &os, const connection_params &x)
std::ostream &	zk::operator<< (std::ostream &os, const error_code &code)
std::string	zk::to_string (const error_code &code)
const std::array< error_code, ZKPP_ERROR_CODE_LIST(ZKPP_ERROR_CODE_SIZE_IMPL)> &	zk::all_error_codes ()
constexpr bool	zk::is_system_error (error_code code)
constexpr bool	zk::is_api_error (error_code code)
void	zk::throw_error (error_code code)
std::exception_ptr	zk::get_exception_ptr_of (error_code code)
std::ostream &	zk::operator<< (std::ostream &os, const op_type &self)
std::string	zk::to_string (const op_type &self)
std::ostream &	zk::operator<< (std::ostream &os, const op &self)
std::string	zk::to_string (const op &self)
std::ostream &	zk::operator<< (std::ostream &os, const multi_op &self)
std::string	zk::to_string (const multi_op &)
std::ostream &	zk::operator<< (std::ostream &os, const multi_result::part &self)
std::ostream &	zk::operator<< (std::ostream &os, const multi_result &self)
std::string	zk::to_string (const multi_result::part &self)
std::string	zk::to_string (const multi_result &self)
std::ostream &	zk::operator<< (std::ostream &os, const get_result &self)
std::string	zk::to_string (const get_result &self)
std::ostream &	zk::operator<< (std::ostream &os, const get_children_result &self)
std::string	zk::to_string (const get_children_result &self)
std::ostream &	zk::operator<< (std::ostream &os, const exists_result &self)
std::string	zk::to_string (const exists_result &self)
std::ostream &	zk::operator<< (std::ostream &os, const create_result &self)
std::string	zk::to_string (const create_result &self)
std::ostream &	zk::operator<< (std::ostream &os, const set_result &self)
std::string	zk::to_string (const set_result &self)
std::ostream &	zk::operator<< (std::ostream &os, const get_acl_result &self)
std::string	zk::to_string (const get_acl_result &self)
std::ostream &	zk::operator<< (std::ostream &os, const event &self)
std::string	zk::to_string (const event &self)
std::ostream &	zk::operator<< (std::ostream &os, const watch_result &self)
std::string	zk::to_string (const watch_result &self)
std::ostream &	zk::operator<< (std::ostream &os, const watch_children_result &self)
std::string	zk::to_string (const watch_children_result &self)
std::ostream &	zk::operator<< (std::ostream &os, const watch_exists_result &self)
std::string	zk::to_string (const watch_exists_result &self)
template<typename TReal , typename TId >
constexpr bool	zk::operator== (const strong_id< TReal, TId > &a, const strong_id< TReal, TId > &b)
template<typename TReal , typename TId >
constexpr bool	zk::operator!= (const strong_id< TReal, TId > &a, const strong_id< TReal, TId > &b)
template<typename TReal , typename TId >
constexpr bool	zk::operator< (const strong_id< TReal, TId > &a, const strong_id< TReal, TId > &b)
template<typename TReal , typename TId >
constexpr bool	zk::operator<= (const strong_id< TReal, TId > &a, const strong_id< TReal, TId > &b)
template<typename TReal , typename TId >
constexpr bool	zk::operator> (const strong_id< TReal, TId > &a, const strong_id< TReal, TId > &b)
template<typename TReal , typename TId >
constexpr bool	zk::operator>= (const strong_id< TReal, TId > &a, const strong_id< TReal, TId > &b)
template<typename TReal , typename TId >
std::size_t	zk::hash (const strong_id< TReal, TId > &x)
std::ostream &	zk::operator<< (std::ostream &os, const version &self)
std::string	zk::to_string (const version &self)
std::ostream &	zk::operator<< (std::ostream &os, const acl_version &self)
std::string	zk::to_string (const acl_version &self)
std::ostream &	zk::operator<< (std::ostream &os, const child_version &self)
std::string	zk::to_string (const child_version &self)
std::ostream &	zk::operator<< (std::ostream &os, const transaction_id &self)
std::string	zk::to_string (const transaction_id &self)
std::ostream &	zk::operator<< (std::ostream &os, const stat &self)
std::string	zk::to_string (const stat &self)
constexpr create_mode	zk::operator| (create_mode a, create_mode b)
constexpr create_mode	zk::operator& (create_mode a, create_mode b)
constexpr create_mode	zk::operator~ (create_mode a)
constexpr bool	zk::is_set (create_mode self, create_mode flags)
	Check that self has flags set. More...
std::ostream &	zk::operator<< (std::ostream &os, const create_mode &mode)
std::string	zk::to_string (const create_mode &self)
std::ostream &	zk::operator<< (std::ostream &os, const event_type &self)
std::string	zk::to_string (const event_type &self)
std::ostream &	zk::operator<< (std::ostream &os, const state &self)
std::string	zk::to_string (const state &self)

Detailed Description

Interacting with ZooKeeper as a client.

Macro Definition Documentation

#define ZKPP_BUFFER_USE_CUSTOM   0

Set this to 1 to use a custom definitions for zk::buffer.

If this is set, you must also set ZKPP_BUFFER_INCLUDE and ZKPP_BUFFER_TYPE.

Definition at line 19 of file buffer.hpp.

#define ZKPP_BUFFER_USE_STD_VECTOR   1

Set this to 1 to use std::vector<char> for the implementation of zk::buffer.

This is the default behavior.

Definition at line 29 of file buffer.hpp.

#define ZKPP_DEBUG   0

Was ZooKeeper C++ compiled in debug mode? This value must be the same between when the SO was built and when you are compiling.

In general, this is not useful outside of library maintainers.

Warning

Keep in mind this value is always defined. Use #if ZKPP_DEBUG, not #ifdef ZKPP_DEBUG.

Definition at line 27 of file config.hpp.

#define ZKPP_FUTURE_INCLUDE   <future>

The file to include to get the implementation for future and promise.

If you define ZKPP_FUTURE_TEMPLATE and ZKPP_PROMISE_TEMPLATE, you must also define this.

Definition at line 52 of file future.hpp.

#define ZKPP_FUTURE_TEMPLATE   std::future

The template to use for zk::future.

By default, this is std::future.

Definition at line 53 of file future.hpp.

#define ZKPP_FUTURE_USE_CUSTOM   0

Set this to 1 to use custom definitions of zk::future and zk::promise.

If this is set, you must also set ZKPP_FUTURE_TEMPLATE, ZKPP_PROMISE_TEMPLATE, and ZKPP_FUTURE_INCLUDE.

Definition at line 36 of file future.hpp.

#define ZKPP_FUTURE_USE_STD   1

Set this to 1 to use std::future and std::promise as the backing types for zk::future and zk::promise.

This is the default behavior.

Definition at line 47 of file future.hpp.

#define ZKPP_FUTURE_USE_STD_EXPERIMENTAL   0

Set this to 1 to use std::experimental::future and std::experimental::promise as the backing types for zk::future and zk::promise.

Definition at line 18 of file future.hpp.

#define ZKPP_NULLOPT_TYPE   std::nullopt_t

The type to use for zk::nullopt_t.

By default, this is std::nullopt_t.

Definition at line 58 of file optional.hpp.

#define ZKPP_NULLOPT_VALUE   std::nullopt

The value to use for zk::nullopt.

By default, this is std::nullopt.

Definition at line 59 of file optional.hpp.

#define ZKPP_OPTIONAL_INCLUDE   <optional>

The file to include to get the implementation for optional, nullopt_t, and nullopt.

By default, this pulls from the standard library.

Definition at line 56 of file optional.hpp.

#define ZKPP_OPTIONAL_TEMPLATE   std::optional

The template to use for zk::optional.

By default, this is std::optional.

Definition at line 57 of file optional.hpp.

#define ZKPP_OPTIONAL_USE_CUSTOM   0

Set this to 1 to use custom definitions for zk::optional, zk::nullopt_t, and zk::nullopt.

If this is set, you must also set ZKPP_OPTIONAL_INCLUDE, ZKPP_NULLOPT_TYPE, and ZKPP_NULLOPT_VALUE.

Definition at line 40 of file optional.hpp.

#define ZKPP_OPTIONAL_USE_STD   1

Set this to 1 to use std::optional, std::nullopt_t, and std::nullopt as the backing types for zk::optional, zk::nullopt_t, and zk::nullopt.

This is the default behavior.

Definition at line 51 of file optional.hpp.

#define ZKPP_OPTIONAL_USE_STD_EXPERIMENTAL   0

Set this to 1 to use std::experimental::optional, std::experimental::nullopt_t, and std::experimental::nullopt as the backing types for zk::optional, zk::nullopt_t, and zk::nullopt.

Definition at line 19 of file optional.hpp.

#define ZKPP_PROMISE_TEMPLATE   std::promise

The template to use for zk::promise.

This should be highly related to ZKPP_FUTURE_TEMPLATE

Definition at line 54 of file future.hpp.

#define ZKPP_SO   1

Are you using shared objects (DLLs in Windows)?

Definition at line 34 of file config.hpp.

Typedef Documentation

using zk::buffer = typedef ZKPP_BUFFER_TYPE

The buffer type.

By default, this is an std::vector<char>, but this can be altered by compile-time flags such as ZKPP_BUFFER_USE_CUSTOM. The requirements for a custom buffer are minimal – the type must fit this criteria:

expression	type	description
buffer::value_type	char	Buffers must be made of single-byte elements
buffer::size_type	std::size_t
buffer(ib, ie)	buffer	Constructs a buffer with the range [ib, ie)
buffer(buffer&&)	buffer	Move constructible.
size()	size_type	Get the length of the buffer
data()	const value_type*	Get a pointer to the beginning of the contents

Definition at line 67 of file buffer.hpp.

template<typename T >

using zk::ptr = typedef T*

A simple, unowned pointer.

It operates exactly like using *, but removes the question of * associativity and is easier to read when const qualifiers are involved.

Definition at line 75 of file config.hpp.

Enumeration Type Documentation

enum zk::create_mode : unsigned int

strong

When used in client::set, this value determines how the znode is created on the server.

These values can be ORed together to create combinations.

Enumerator
normal	Standard behavior of a znode – the opposite of doing any of the options.
ephemeral	The znode will be deleted upon the client's disconnect.
sequential	The name of the znode will be appended with a monotonically increasing number. The actual path name of a sequential node will be the given path plus a suffix "i" where i is the current sequential number of the node. The sequence number is always fixed length of 10 digits, 0 padded. Once such a node is created, the sequential number will be incremented by one.
container	Container nodes are special purpose nodes useful for recipes such as leader, lock, etc. When the last child of a container is deleted, the container becomes a candidate to be deleted by the server at some point in the future. Given this property, you should be prepared to get no_node when creating children inside of this container node.

Definition at line 252 of file types.hpp.

enum zk::event_type : int

strong

Enumeration of types of events that may occur.

Enumerator
error	Invalid event (this should never be issued).
created	Issued when a znode at a given path is created.
erased	Issued when a znode at a given path is erased.
changed	Issued when the data of a watched znode are altered. This event value is issued whenever a set operation occurs without an actual contents check, so there is no guarantee the data actually changed.
child	Issued when the children of a watched znode are created or deleted. This event is not issued when the data within children is altered.
session	This value is issued as part of an event when the state changes.
not_watching	Watch has been forcefully removed. This is generated when the server for some reason (probably a resource constraint), will no longer watch a node for a client.

Definition at line 298 of file types.hpp.

enum zk::permission : unsigned int

strong

Describes the ability of a user to perform a certain action.

Permissions can be mixed together like integers with | and &.

Enumerator
none	No permissions are set (server could have been configured without ACL support).
read	You can access the data of a node and can list its children.
write	You can set the data of a node.
create	You can create a child node.
erase	You can erase a child node (but not necessarily this one).
admin	You can alter permissions on this node.
all	You can do anything.

Definition at line 23 of file acl.hpp.

enum zk::state : int

strong

Enumeration of states the client may be at when a watch triggers.

It represents the state of the connection at the time the event was generated.

Enumerator
closed	The client is not connected to any server in the ensemble.
connecting	The client is connecting.
associating	Client is attempting to associate a session.
connected	The client is in the connected state – it is connected to a server in the ensemble (one of the servers specified in the host connection parameter during ZooKeeper client creation).
read_only	The client is connected to a read-only server, that is the server which is not currently connected to the majority. The only operations allowed after receiving this state is read operations. This state is generated for read-only clients only since read/write clients aren't allowed to connect to read-only servers.
expired_session	The serving cluster has expired this session. The ZooKeeper client connection (the session) is no longer valid. You must create a new client connection if you with to access the ensemble.
authentication_failed	Authentication has failed – connection requires a new connection instance with different credentials.

Definition at line 320 of file types.hpp.

Function Documentation

constexpr bool zk::allows	(	permission	self,
		permission	perform
	)

Check that self allows it perform all operations.

For example, allows(permission::read | permission::write, permission::read) will be true, as read|write is allowed to read.

Definition at line 53 of file acl.hpp.

constexpr bool zk::is_set	(	create_mode	self,
		create_mode	flags
	)

Check that self has flags set.

Definition at line 288 of file types.hpp.