PING

Detailed Description

Broadcast NOOP-like commands to each service in the cluster.

Functions
lcb_error_t	lcb_ping3 (lcb_t instance, const void *cookie, const lcb_CMDPING *cmd)
	Check connections by sending NOOP-like messages to all services. More...
lcb_error_t	lcb_diag (lcb_t instance, const void *cookie, const lcb_CMDDIAG *cmd)
	Returns diagnostics report about network connections. More...

Macros
#define	LCB_PINGSVC_F_KV
	Ping data (Key/Value) service. More...
#define	LCB_PINGSVC_F_N1QL
	Ping query (N1QL) service. More...
#define	LCB_PINGSVC_F_VIEWS
	Ping views (Map/Reduce) service. More...
#define	LCB_PINGSVC_F_FTS
	Ping full text search (FTS) service. More...
#define	LCB_PINGSVC_F_ANALYTICS
	Ping Analytics for N1QL service. More...
#define	LCB_PINGOPT_F_NOMETRICS
	Do not record any metrics or status codes from ping responses. More...
#define	LCB_PINGOPT_F_JSON
	Automatically encode PING result as JSON. More...
#define	LCB_PINGOPT_F_JSONDETAILS
	Add extra details about service status into generated JSON. More...
#define	LCB_PINGOPT_F_JSONPRETTY
	Generate indented JSON, which is better for reading. More...

Enumerations
enum	lcb_PINGSVCTYPE
	Type of the service. More...
enum	lcb_PINGSTATUS
	Status of the service More...

Function Documentation

lcb_ping3()

lcb_error_t lcb_ping3	(	lcb_t	instance,
		const void *	cookie,
		const lcb_CMDPING *	cmd
	)

Check connections by sending NOOP-like messages to all services.

Stability

Committed:

When no metrics, required, it is possible to reduce memory overhead by turning off response contents using LCB_PINGOPT_F_NOMETRICS.

Request

lcb_CMDPING cmd = { 0 };
// select services to ping
cmd.services = LCB_PINGSVC_F_KV | LCB_PINGSVC_F_N1QL;
lcb_ping3(instance, fp, &cmd);
lcb_wait(instance);

Response

lcb_install_callback3(instance, LCB_CALLBACK_PING, ping_callback);
void ping_callback(lcb_t, int, const lcb_RESPBASE *rb)
{
    const lcb_RESPPING *resp = (const lcb_RESPPING*)rb;
    int ii;
    for (ii = 0; ii < resp->nservices; ii++) {
        printf("service: %s, status: %d, host: %s, latency: %lu nanoseconds\n",
            resp->services[ii].type == LCB_PINGSVC_KV ? "KV" : "N1QL",
            resp->services[ii].status,
            resp->services[ii].server,
            (unsigned long)resp->services[ii].latency);
    }
}

Parameters

instance	the library handle
cookie	the cookie passed in the callback
cmd	empty command structure.

Returns

status code for scheduling.

lcb_diag()

lcb_error_t lcb_diag	(	lcb_t	instance,
		const void *	cookie,
		const lcb_CMDDIAG *	cmd
	)

Returns diagnostics report about network connections.

Stability

Committed:

Request

lcb_CMDDIAG cmd = { 0 };
lcb_diag(instance, fp, &cmd);
lcb_wait(instance);

Response

lcb_install_callback3(instance, LCB_CALLBACK_DIAG, diag_callback);
void diag_callback(lcb_t, int, const lcb_RESPBASE *rb)
{
    const lcb_RESPDIAG *resp = (const lcb_RESPDIAG *)rb;
    if (resp->rc != LCB_SUCCESS) {
        fprintf(stderr, "failed: %s\n", lcb_strerror(NULL, resp->rc));
    } else {
        if (resp->njson) {
            fprintf(stderr, "\n%.*s", (int)resp->njson, resp->json);
        }
    }
}

Parameters

instance	the library handle
cookie	the cookie passed in the callback
cmd	command structure.

Returns

status code for scheduling.

---

Data Structure Documentation

lcb_CMDPING

struct lcb_CMDPING

Structure for PING requests.

Stability

Committed:

Data Fields
lcb_U32	cmdflags	Common flags for the command. These modify the command itself. Currently the lower 16 bits of this field are reserved, and the higher 16 bits are used for individual commands.
lcb_U32	exptime	Specify the expiration time. This is either an absolute Unix time stamp or a relative offset from now, in seconds. If the value of this number is greater than the value of thirty days in seconds, then it is a Unix timestamp. This field is used in mutation operations (lcb_store3()) to indicate the lifetime of the item. It is used in lcb_get3() with the lcb_CMDGET::lock option to indicate the lock expiration itself.
lcb_U64	cas	The known CAS of the item. This is passed to mutation to commands to ensure the item is only changed if the server-side CAS value matches the one specified here. For other operations (such as lcb_CMDENDURE) this is used to ensure that the item has been persisted/replicated to a number of servers with the value specified here.
lcb_KEYBUF	key	The key for the document itself. This should be set via LCB_CMD_SET_KEY()
lcb_KEYBUF	_hashkey	Stability Volatile:
int	services	bitmap for services to ping
int	options	extra options, e.g. for result representation
const char *	id	optional, zero-terminated string to identify the report

lcb_PINGSVC

struct lcb_PINGSVC

Entry describing the status of the service in the cluster.

It is part of lcb_RESPING structure.

Stability

Committed:

Data Fields
lcb_PINGSVCTYPE	type	type of the service
const char *	server	server host:port
lcb_U64	latency	latency in nanoseconds
lcb_error_t	rc	raw return code of the operation
const char *	local	server host:port
const char *	id	service identifier (unique in scope of lcb_t connection instance)
const char *	scope	optional scope name (typically equals to the bucket name)
lcb_PINGSTATUS	status	status of the operation

lcb_RESPPING

struct lcb_RESPPING

Structure for PING responses.

Stability

Committed:

Data Fields
void *	cookie	Application-defined pointer passed as the cookie parameter when scheduling the command.
const void *	key	Key for request.
lcb_SIZE	nkey	Size of key.
lcb_CAS	cas	CAS for response (if applicable)
lcb_error_t	rc	Status code.
lcb_U16	version	ABI version for response.
lcb_U16	rflags	Response specific flags. see lcb_RESPFLAGS
const char *	server	String containing the host:port of the server which sent this response.
lcb_SIZE	nservices	number of the nodes, replied to ping
lcb_PINGSVC *	services	the nodes, replied to ping, if any
lcb_SIZE	njson	length of JSON string (when LCB_PINGOPT_F_JSON was specified)
const char *	json	pointer to JSON string

Macro Definition Documentation

LCB_PINGSVC_F_KV

#define LCB_PINGSVC_F_KV

Ping data (Key/Value) service.

Used in lcb_CMDPING::services

LCB_PINGSVC_F_N1QL

#define LCB_PINGSVC_F_N1QL

Ping query (N1QL) service.

Used in lcb_CMDPING::services

LCB_PINGSVC_F_VIEWS

#define LCB_PINGSVC_F_VIEWS

Ping views (Map/Reduce) service.

Used in lcb_CMDPING::services

LCB_PINGSVC_F_FTS

#define LCB_PINGSVC_F_FTS

Ping full text search (FTS) service.

Used in lcb_CMDPING::services

LCB_PINGSVC_F_ANALYTICS

#define LCB_PINGSVC_F_ANALYTICS

Ping Analytics for N1QL service.

Used in lcb_CMDPING::services

LCB_PINGOPT_F_NOMETRICS

#define LCB_PINGOPT_F_NOMETRICS

Do not record any metrics or status codes from ping responses.

This might be useful to reduce overhead, when user-space keep-alive mechanism is not interested in actual latencies, but rather need keep sockets active. Used in lcb_CMDPING::options

LCB_PINGOPT_F_JSON

#define LCB_PINGOPT_F_JSON

Automatically encode PING result as JSON.

See njson/json fields of lcb_RESPPING structure. Used in lcb_CMDPING::options

LCB_PINGOPT_F_JSONDETAILS

#define LCB_PINGOPT_F_JSONDETAILS

Add extra details about service status into generated JSON.

Requires LCB_PINGOPT_F_JSON to be set. Used in lcb_CMDPING::options

LCB_PINGOPT_F_JSONPRETTY

#define LCB_PINGOPT_F_JSONPRETTY

Generate indented JSON, which is better for reading.

Used in lcb_CMDPING::options

Enumeration Type Documentation

lcb_PINGSVCTYPE

enum lcb_PINGSVCTYPE

Type of the service.

This enumeration is used in PING responses.

Stability

Committed:

lcb_PINGSTATUS

enum lcb_PINGSTATUS

Status of the service

Stability

Committed: