Couchbase C Client  2.9.4
Asynchronous C Client for Couchbase

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_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
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
instancethe library handle
cookiethe cookie passed in the callback
cmdempty 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
instancethe library handle
cookiethe cookie passed in the callback
cmdcommand 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_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


Type of the service.

This enumeration is used in PING responses.

Stability
Committed:

◆ lcb_PINGSTATUS


Status of the service

Stability
Committed: