A ZooKeeper client connection. More...

#include <zk/client.hpp>

Public Member Functions
	client (string_view conn_string)
	Create a client connected to the cluster specified by `conn_string`. More...

	client (std::shared_ptr< connection > conn) noexcept
	Create a client connected with conn. More...

	client (const client &) noexcept=default

	client (client &&) noexcept=default

client &	operator= (const client &) noexcept=default

client &	operator= (client &&) noexcept=default

void	close ()

future< get_result >	get (string_view path) const
	Return the data and the `stat` of the node of the given path. More...

future< watch_result >	watch (string_view path) const
	Similar to `get`, but if the call is successful (no error is returned), a watch will be left on the node with the given path. More...

future< get_children_result >	get_children (string_view path) const
	Return the list of the children of the node of the given path. More...

future< watch_children_result >	watch_children (string_view path) const
	Similar to `get_children`, but if the call is successful (no error is returned), a watch will be left on the node with the given path. More...

future< exists_result >	exists (string_view path) const
	Return the `stat` of the node of the given path or `nullopt` if no such node exists. More...

future< watch_exists_result >	watch_exists (string_view path) const
	Similar to `watch`, but if the call is successful (no error is returned), a watch will be left on the node with the given path. More...

future< create_result >	create (string_view path, const buffer &data, const acl &rules, create_mode mode=create_mode::normal)
	Create a node with the given path. More...

future< create_result >	create (string_view path, const buffer &data, create_mode mode=create_mode::normal)

future< set_result >	set (string_view path, const buffer &data, version check=version::any())
	Set the data for the node of the given path if such a node exists and the given version matches the version of the node (if the given version is `version::any`, there is no version check). More...

future< get_acl_result >	get_acl (string_view path) const
	Return the ACL and `stat` of the node of the given path. More...

future< void >	set_acl (string_view path, const acl &rules, acl_version check=acl_version::any())
	Set the ACL for the node of the given path if such a node exists and the given version check matches the version of the node. More...

future< void >	erase (string_view path, version check=version::any())
	Erase the node with the given path. More...

future< void >	load_fence () const
	Ensure that all subsequent reads observe the data at the transaction on the server at or past real-time now. More...

future< multi_result >	commit (multi_op txn)
	Commit the transaction specified by txn. More...

Static Public Member Functions
static future< client >	connect (string_view conn_string)
	Create a client connected to the cluster specified by `conn_string`. More...

Detailed Description

A ZooKeeper client connection.

This is the primary class for interacting with the ZooKeeper cluster. The best way to create a client is with the static connect function.

Definition at line 27 of file client.hpp.

Constructor & Destructor Documentation

zk::client::client ( string_view conn_string )

explicit

Create a client connected to the cluster specified by conn_string.

See connection::connect for documentation on connection strings.

Definition at line 16 of file client.cpp.

zk::client::client ( std::shared_ptr< connection > conn )

explicitnoexcept

Create a client connected with conn.

Definition at line 20 of file client.cpp.

Member Function Documentation

future< multi_result > zk::client::commit ( multi_op txn )

Commit the transaction specified by txn.

The operations are performed atomically: They will either all succeed or all fail.

Exceptions

transaction_failed	If the transaction does not complete with an error in the transaction itself (any `error_code` that fits `is_api_error`), the future will be delivered with `transaction_failed`. Check the thrown `transaction_failed::underlying_cause` for more information.
system_error	For the same reasons any other operation might fail, the future will be delivered with a specific `system_error`.

Definition at line 140 of file client.cpp.

future< client > zk::client::connect ( string_view conn_string )

static

Create a client connected to the cluster specified by conn_string.

See connection::connect for documentation on connection strings.

Returns: A future which will be filled when the conneciton is established. The future will be filled in error if the client will never be able to connect to the cluster (for example: a bad connection string).

Definition at line 24 of file client.cpp.

future< create_result > zk::client::create	(	string_view	path,
		const buffer &	data,
		const acl &	rules,
		create_mode	mode = `create_mode::normal`
	)

Create a node with the given path.

This operation, if successful, will trigger all the watches left on the node of the given path by watch API calls, and the watches left on the parent node by watch_children API calls.

Parameters

path	The path or path pattern (if using `create_mode::sequential`) to create.
data	The data to create inside the node.
mode	Specifies the behavior of the created node (see `create_mode` for more information).
rules	The ACL for the created znode. If unspecified, it is equivalent to providing `acls::open_unsafe`.

Returns: A future which will be filled with the name of the created znode and its stat.

Exceptions

node_exists	If a node with the same actual path already exists in the ZooKeeper, the future will be delivered with `node_exists`. Note that since a different actual path is used for each invocation of creating sequential node with the same path argument, the call should never error in this manner.
no_node	If the parent node does not exist in the ZooKeeper, the future will be delivered with `no_node`.
no_children_for_ephemerals	An ephemeral node cannot have children. If the parent node of the given path is ephemeral, the future will be delivered with `no_children_for_ephemerals`.
invalid_acl	If the acl is invalid or empty, the future will be delivered with `invalid_acl`.
invalid_arguments	The maximum allowable size of the data array is 1 MiB (1,048,576 bytes). If data is larger than this the future will be delivered with `invalid_arguments`.

Definition at line 98 of file client.cpp.

future< void > zk::client::erase	(	string_view	path,
		version	check = `version::any()`
	)

Erase the node with the given path.

The call will succeed if such a node exists, and the given version check matches the node's version (if the given version is version::any, it matches any node's versions). This operation, if successful, will trigger all the watches on the node of the given path left by watch API calls, watches left by watch_exists API calls, and the watches on the parent node left by watch_children API calls.

Exceptions

no_node	If no node with the given path exists, the future will be delivered with `no_node`.
bad_version	If the given version check does not match the node's version, the future will be delivered with `bad_version`.
not_empty	You are only allowed to erase nodes with no children. If the node has children, the future will be delievered with `not_empty`.

Definition at line 130 of file client.cpp.

future< exists_result > zk::client::exists ( string_view path ) const

Return the stat of the node of the given path or nullopt if no such node exists.

Definition at line 88 of file client.cpp.

future< get_result > zk::client::get ( string_view path ) const

Return the data and the stat of the node of the given path.

Exceptions

no_node If no node with the given path exists, the future will be deliever with no_node.

Definition at line 68 of file client.cpp.

future< get_acl_result > zk::client::get_acl ( string_view path ) const

Return the ACL and stat of the node of the given path.

Exceptions

no_node If no node with the given path exists, the future will be deliever with no_node.

Definition at line 120 of file client.cpp.

future< get_children_result > zk::client::get_children ( string_view path ) const

Return the list of the children of the node of the given path.

The returned values are not prefixed with the provided path; i.e. if the database contains "/path/a" and "/path/b", the result of get_children for "/path" will be ["a", "b"]. The list of children returned is not sorted and no guarantee is provided as to its natural or lexical order.

Exceptions

no_node If no node with the given path exists, the future will be delivered with no_node.

Definition at line 78 of file client.cpp.

future< void > zk::client::load_fence ( ) const

Ensure that all subsequent reads observe the data at the transaction on the server at or past real-time now.

If your application communicates only through reads and writes of ZooKeeper, this operation is never needed. However, if your application communicates a change in ZooKeeper state through means outside of ZooKeeper (called a "hidden channel" in ZooKeeper vernacular), then it is possible for a receiver to attempt to react to a change before it can observe it through ZooKeeper state.

Warning: The internal pipeline for this operation is not the same as modifying operations (set, create, etc.). In cases of leader failure, there is a chance that the leader does not have support from the quorum, as it has switched to a new leader. While this is rare, it is still possible that not all updates have been processed.

Note: Other APIs call this operation sync and allow you to provide a path parameter. There are a few issues with this. First: that name conflicts with the commonly-used POSIX sync command, leading to confusion that data in ZooKeeper does not have integrity. Secondly, this operation has more in common with std::atomic_thread_fence or the x86 lfence instruction than sync (on the server, "flush" is an appropriate term – just like fence implementations in CPUs). Finally, the path parameter is ignored by the server – all future fetches are fenced, no matter what path is specified. In the future, ZooKeeper might support partitioning, in which case the path parameter might become relevant.

It is often not necessary to wait for the fence future to be returned, as future reads will be synced without waiting. However, there is no guarantee on the ordering of the read if the future returned from load_fence is completed in error.

auto fence_future = client.load_fence();
// data_future will be completed with the load_fence, even though we haven't waited to complete
auto data_future = client.get("/some/path");
// Useful to use when_all to concat and error check (C++ Extensions for Concurrency, ISO/IEC TS 19571:2016)
auto guaranteed_future = std::when_all(std::move(fence_future), std::move(data_future));

Definition at line 135 of file client.cpp.

future< set_result > zk::client::set	(	string_view	path,
		const buffer &	data,
		version	check = `version::any()`
	)

Set the data for the node of the given path if such a node exists and the given version matches the version of the node (if the given version is version::any, there is no version check).

This operation, if successful, will trigger all the watches on the node of the given path left by watch calls.

Exceptions

no_node	If no node with the given path exists, the future will be delivered with `no_node`.
bad_version	If the given version check does not match the node's version, the future will be delivered with `bad_version`.
invalid_arguments	The maximum allowable size of the data array is 1 MiB (1,048,576 bytes). If data is larger than this the future will be delivered with `invalid_arguments`.

Definition at line 115 of file client.cpp.

future< void > zk::client::set_acl	(	string_view	path,
		const acl &	rules,
		acl_version	check = `acl_version::any()`
	)

Set the ACL for the node of the given path if such a node exists and the given version check matches the version of the node.

Parameters

check If specified, check that the ACL matches. Keep in mind this is the acl_version, not the data version – there is no way to have this operation fail on changes to stat::data_version.

Exceptions

no_node	If no node with the given path exists, the future will be delivered with `no_node`.
bad_version	If the given version check does not match the node's version, the future will be delivered with `bad_version`.

Definition at line 125 of file client.cpp.

future< watch_result > zk::client::watch ( string_view path ) const

Similar to get, but if the call is successful (no error is returned), a watch will be left on the node with the given path.

The watch will be triggered by a successful operation that sets data on the node or erases the node.

Exceptions

no_node If no node with the given path exists, the future will be deliever with no_node. To watch for the creation of a node, use watch_exists.

Definition at line 73 of file client.cpp.

future< watch_children_result > zk::client::watch_children ( string_view path ) const

Similar to get_children, but if the call is successful (no error is returned), a watch will be left on the node with the given path.

The watch will be triggered by a successful operation that erases the node of the given path or creates or erases a child under the node.

Definition at line 83 of file client.cpp.

future< watch_exists_result > zk::client::watch_exists ( string_view path ) const

Similar to watch, but if the call is successful (no error is returned), a watch will be left on the node with the given path.

The watch will be triggered by a successful operation that creates the node, erases the node, or sets the data on the node.

Definition at line 93 of file client.cpp.

The documentation for this class was generated from the following files:

zk/client.hpp
zk/client.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation