A ZooKeeper client connection. More...

#include <zk/client.hpp>

Public Member Functions
	client (const connection_params &params)
	Create a client connected to the cluster specified by params. More...

	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 ()
	Close the underlying connection. More...

future< get_result >	get (string_view path) const
	Return the data and the stat of the entry 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 entry with the given path. More...

future< get_children_result >	get_children (string_view path) const
	Return the list of the children of the entry 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 entry with the given path. More...

future< exists_result >	exists (string_view path) const
	Return the stat of the entry of the given path or `nullopt` if it does not exist. 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 entry with the given path. More...

future< set_result >	set (string_view path, const buffer &data, version check=version::any())
	Set the data for the entry of the given path if such an entry exists and the given version matches the version of the entry (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 entry 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 entry of the given path if such an entry exists and the given version check matches the version of the entry. More...

future< void >	erase (string_view path, version check=version::any())
	Erase the entry at 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...


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

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

Static Public Member Functions

static future< client >	connect (string_view conn_string)

static future< client >	connect (connection_params conn_params)

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 25 of file client.hpp.

Constructor & Destructor Documentation

zk::client::client ( const connection_params & params )

explicit

Create a client connected to the cluster specified by params.

Definition at line 16 of file client.cpp.

zk::client::client ( string_view conn_string )

explicit

Create a client connected to the cluster specified by conn_string.

Parameters

conn_string A ZooKeeper connection string.

Definition at line 20 of file client.cpp.

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

explicitnoexcept

Create a client connected with conn.

Definition at line 24 of file client.cpp.

Member Function Documentation

void zk::client::close ( )

Close the underlying connection.

All outstanding operations will be cancelled and all watches will be delivered with closed. You usually do not need to call this operation, as the destructor handles this automatically.

Definition at line 72 of file client.cpp.

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 149 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.

Parameters

conn_string A ZooKeeper connection string.

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 28 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 an entry at the given path.

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

Parameters

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

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

Exceptions

entry_exists	If an entry with the same actual path already exists in the ZooKeeper, the future will be delivered with entry_exists. Note that since a different actual path is used for each invocation of creating sequential entry with the same path argument, the call should never error in this manner.
no_entry	If the parent of the given path does not exist, the future will be delievered with no_entry.
no_children_for_ephemerals	An ephemeral entry cannot have children. If the parent entry 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 107 of file client.cpp.

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

Erase the entry at the given path.

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

Exceptions

no_entry	If no entry exists at the given path, the future will be delievered with no_entry.
version_mismatch	If the given version check does not match the entry's version, the future will be delivered with version_mismatch.
not_empty	You are only allowed to erase entries with no children. If the entry has children, the future will be delievered with not_empty.

Definition at line 139 of file client.cpp.

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

Return the stat of the entry of the given path or nullopt if it does not exist.

Definition at line 97 of file client.cpp.

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

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

Exceptions

no_entry If no entry exists at the given path, the future will be delievered with no_entry.

Definition at line 77 of file client.cpp.

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

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

Exceptions

no_entry If no entry exists at the given path, the future will be delievered with no_entry.

Definition at line 129 of file client.cpp.

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

Return the list of the children of the entry 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_entry If no entry exists at the given path, the future will be delievered with no_entry.

Definition at line 87 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 144 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 entry of the given path if such an entry exists and the given version matches the version of the entry (if the given version is version::any, there is no version check).

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

Exceptions

no_entry	If no entry exists at the given path, the future will be delievered with no_entry.
version_mismatch	If the given version check does not match the entry's version, the future will be delivered with version_mismatch.
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 124 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 entry of the given path if such an entry exists and the given version check matches the version of the entry.

Parameters

check If specified, check that the ACL version 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 without the use of a multi_op.

Exceptions

no_entry	If no entry exists at the given path, the future will be delievered with no_entry.
version_mismatch	If the given version check does not match the entry's version, the future will be delivered with version_mismatch.

Definition at line 134 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 entry with the given path.

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

Exceptions

no_entry If no entry exists at the given path, the future will be delievered with no_entry. To watch for the creation of an entry, use watch_exists.

Definition at line 82 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 entry with the given path.

The watch will be triggered by a successful operation that erases the entry at the given path or creates or erases a child immediately under the path (it is not recursive).

Definition at line 92 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 entry with the given path.

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

Definition at line 102 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