A handle to the LogCabin cluster. More...

#include <Client.h>

Public Types
typedef std::map< std::string, std::string >	Options
	Settings for the client library.
Public Member Functions
	Cluster (std::shared_ptr< TestingCallbacks > testingCallbacks, const Options &options=Options())
	Construct a Cluster object for testing purposes only.
	Cluster (const std::string &hosts, const Options &options=Options())
	Constructor.
	~Cluster ()
	Destructor.
std::pair< uint64_t, Configuration >	getConfiguration () const
	Get the current, stable cluster configuration.
GetConfigurationResult	getConfiguration2 (uint64_t timeoutNanoseconds) const
	Get the current, stable cluster configuration.
GetConfigurationResult	getConfiguration2Ex (uint64_t timeoutNanoseconds) const
	Like getConfiguration2 but throws exceptions upon errors.
ConfigurationResult	setConfiguration (uint64_t oldId, const Configuration &newConfiguration)
	Change the cluster's configuration.
ConfigurationResult	setConfiguration2 (uint64_t oldId, const Configuration &newConfiguration, uint64_t timeoutNanoseconds)
	Like setConfiguration but allows a timeout.
ConfigurationResult	setConfiguration2Ex (uint64_t oldId, const Configuration &newConfiguration, uint64_t timeoutNanoseconds)
	Like setConfiguration2 but throws exceptions upon errors.
Result	getServerInfo (const std::string &host, uint64_t timeoutNanoseconds, Server &info)
	Retrieve basic information from the given server, like its ID and the addresses on which it is listening.
Server	getServerInfoEx (const std::string &host, uint64_t timeoutNanoseconds)
	Like getServerInfo but throws exceptions upon errors.
Result	getServerStats (const std::string &host, uint64_t timeoutNanoseconds, Protocol::ServerStats &stats)
	Retrieve statistics from the given server, which are useful for diagnostics.
Protocol::ServerStats	getServerStatsEx (const std::string &host, uint64_t timeoutNanoseconds)
	Like getServerStats but throws exceptions upon errors.
Tree	getTree ()
	Return an object to access the hierarchical key-value store.
Private Attributes
std::shared_ptr< ClientImpl >	clientImpl

Detailed Description

A handle to the LogCabin cluster.

If the client requests changes to the cluster's replicated state machine (for example, by writing a value), the client library will first open a session with the cluster. It will thereafter periodically send keep-alive requests to the cluster during periods of inactivity to maintain this session. If communication to the LogCabin cluster is lost for an extended period of time, the client's session will expire, and this library will force the client to crash.

Definition at line 654 of file Client.h.

Member Typedef Documentation

typedef std::map<std::string, std::string> LogCabin::Client::Cluster::Options

Settings for the client library.

These are all optional. Currently supported options:

clusterUUID (see sample.conf)
tcpHeartbeatTimeoutMilliseconds (see sample.conf)
tcpConnectTimeoutMilliseconds (see sample.conf)
sessionCloseTimeoutMilliseconds: This Cluster object opens a session with LogCabin before issuing any read-write commands to the replicated state machine. When this Cluster object is destroyed, it will attempt to close its session gracefully. This timeout controls the number of milliseconds that the client will wait until giving up on the close session RPC. It defaults to tcpConnectTimeoutMilliseconds, since they should be on the same order of magnitude.

Definition at line 672 of file Client.h.

Constructor & Destructor Documentation

LogCabin::Client::Cluster::Cluster	(	std::shared_ptr< TestingCallbacks >	testingCallbacks,
		const Options &	options = `Options()`
	)		`[explicit]`

Construct a Cluster object for testing purposes only.

Instead of connecting to a LogCabin cluster, it will keep all state locally in memory.

This is experimental and is not part of LogCabin's public API.

Parameters:

testingCallbacks	These allow the application to interpose on requests. A default-constructed TestingCallbacks will execute requests against an in-memory structure. Applications can pass in classes derived from TestingCallbacks to model failures and more dynamic scenarios.
options	Settings for the client library (see Options).

Definition at line 510 of file Client.cc.

LogCabin::Client::Cluster::Cluster	(	const std::string &	hosts,
		const Options &	options = `Options()`
	)		`[explicit]`

Constructor.

Parameters:

hosts	A string describing the hosts in the cluster. This should be of the form host:port, where host is usually a DNS name that resolves to multiple IP addresses. Alternatively, you can pass a list of hosts as host1:port1,host2:port2,host3:port3.
options	Settings for the client library (see Options).

Definition at line 519 of file Client.cc.

LogCabin::Client::Cluster::~Cluster ( )

Destructor.

Definition at line 530 of file Client.cc.

Member Function Documentation

std::pair< uint64_t, Configuration > LogCabin::Client::Cluster::getConfiguration ( ) const

Get the current, stable cluster configuration.

Returns:: first: configurationId: Identifies the configuration. Pass this to setConfiguration later. second: The list of servers in the configuration.

Definition at line 535 of file Client.cc.

GetConfigurationResult LogCabin::Client::Cluster::getConfiguration2 ( uint64_t timeoutNanoseconds ) const

Get the current, stable cluster configuration.

Parameters:

timeoutNanoseconds Amount of time to wait for getConfiguration to complete. Passing 0 indicates that no timeout is desired.

Returns:: See GetConfigurationResult

Since:: LogCabin v1.2.0.

Definition at line 543 of file Client.cc.

GetConfigurationResult LogCabin::Client::Cluster::getConfiguration2Ex ( uint64_t timeoutNanoseconds ) const

Like getConfiguration2 but throws exceptions upon errors.

Since:: LogCabin v1.2.0.

Definition at line 550 of file Client.cc.

ConfigurationResult LogCabin::Client::Cluster::setConfiguration	(	uint64_t	oldId,
		const Configuration &	newConfiguration
	)

Change the cluster's configuration.

Parameters:

oldId	The ID of the cluster's current configuration.
newConfiguration	The list of servers in the new configuration.

Definition at line 560 of file Client.cc.

ConfigurationResult LogCabin::Client::Cluster::setConfiguration2	(	uint64_t	oldId,
		const Configuration &	newConfiguration,
		uint64_t	timeoutNanoseconds
	)

Like setConfiguration but allows a timeout.

Parameters:

oldId	The ID of the cluster's current configuration.
newConfiguration	The list of servers in the new configuration.
timeoutNanoseconds	Amount of time to wait for the call to complete. 0=wait forever

Since:: LogCabin v1.2.0.

Definition at line 568 of file Client.cc.

ConfigurationResult LogCabin::Client::Cluster::setConfiguration2Ex	(	uint64_t	oldId,
		const Configuration &	newConfiguration,
		uint64_t	timeoutNanoseconds
	)

Like setConfiguration2 but throws exceptions upon errors.

Since:: LogCabin v1.2.0.

Definition at line 577 of file Client.cc.

Result LogCabin::Client::Cluster::getServerInfo	(	const std::string &	host,
		uint64_t	timeoutNanoseconds,
		Server &	info
	)

Retrieve basic information from the given server, like its ID and the addresses on which it is listening.

Parameters:

host	The hostname or IP address of the server to retrieve stats from. It is recommended that you do not use a DNS name that resolves to multiple hosts here.
timeoutNanoseconds	Abort the operation if it has not completed within the specified period of time. Time is specified in nanoseconds, and the special value of 0 indicates no timeout.

Warning:: The client library does not currently implement timeouts for DNS lookups. See https://github.com/logcabin/logcabin/issues/75

Parameters:

[out] info Protocol buffer of Stats as retrieved from the server.

Returns:: Either OK or TIMEOUT.

Definition at line 597 of file Client.cc.

Server LogCabin::Client::Cluster::getServerInfoEx	(	const std::string &	host,
		uint64_t	timeoutNanoseconds
	)

Like getServerInfo but throws exceptions upon errors.

Definition at line 608 of file Client.cc.

Result LogCabin::Client::Cluster::getServerStats	(	const std::string &	host,
		uint64_t	timeoutNanoseconds,
		Protocol::ServerStats &	stats
	)

Retrieve statistics from the given server, which are useful for diagnostics.

Parameters:

host	The hostname or IP address of the server to retrieve stats from. It is recommended that you do not use a DNS name that resolves to multiple hosts here.
timeoutNanoseconds	Abort the operation if it has not completed within the specified period of time. Time is specified in nanoseconds, and the special value of 0 indicates no timeout.

Warning:: The client library does not currently implement timeouts for DNS lookups. See https://github.com/logcabin/logcabin/issues/75

Parameters:

[out] stats Protocol buffer of Stats as retrieved from the server.

Returns:: Either OK or TIMEOUT.

Definition at line 618 of file Client.cc.

Protocol::ServerStats LogCabin::Client::Cluster::getServerStatsEx	(	const std::string &	host,
		uint64_t	timeoutNanoseconds
	)

Like getServerStats but throws exceptions upon errors.

Definition at line 636 of file Client.cc.

Tree LogCabin::Client::Cluster::getTree ( )

Return an object to access the hierarchical key-value store.

Returns:: A Tree object with the working directory of '/'.

Definition at line 646 of file Client.cc.

Member Data Documentation

std::shared_ptr<ClientImpl> LogCabin::Client::Cluster::clientImpl [private]

Definition at line 841 of file Client.h.

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

include/LogCabin/Client.h
Client/Client.cc

Public Types

Public Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation