Couchbase C Client  2.10.7
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_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
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_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

Type of the service.

This enumeration is used in PING responses.

Stability
Committed:

◆ lcb_PINGSTATUS

Status of the service.

Stability
Committed:
lcb_wait
lcb_error_t lcb_wait(lcb_t instance)
Wait for the execution of all batched requests.
LCB_PINGSVC_F_KV
#define LCB_PINGSVC_F_KV
Ping data (Key/Value) service.
Definition: couchbase.h:2437
lcb_strerror
const char * lcb_strerror(lcb_t instance, lcb_error_t error)
Get a textual descrtiption for the given error code.
lcb_RESPPING
Structure for PING responses.
Definition: couchbase.h:2545
lcb_diag
lcb_error_t lcb_diag(lcb_t instance, const void *cookie, const lcb_CMDDIAG *cmd)
Returns diagnostics report about network connections.
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.
lcb_PINGSVC::type
lcb_PINGSVCTYPE type
type of the service
Definition: couchbase.h:2529
LCB_PINGSVC_F_N1QL
#define LCB_PINGSVC_F_N1QL
Ping query (N1QL) service.
Definition: couchbase.h:2442
lcb_RESPPING::nservices
lcb_SIZE nservices
number of the nodes, replied to ping
Definition: couchbase.h:2548
lcb_RESPPING::services
lcb_PINGSVC * services
the nodes, replied to ping, if any
Definition: couchbase.h:2549
lcb_PINGSVC::server
const char * server
server host:port
Definition: couchbase.h:2531
lcb_t
struct lcb_st * lcb_t
Definition: couchbase.h:41
lcb_CMDPING::services
int services
bitmap for services to ping
Definition: couchbase.h:2491
LCB_SUCCESS
@ LCB_SUCCESS
Success.
Definition: error.h:478
lcb_CMDPING
Structure for PING requests.
Definition: couchbase.h:2489
lcb_PINGSVC::latency
lcb_U64 latency
latency in nanoseconds
Definition: couchbase.h:2532
LCB_CALLBACK_PING
@ LCB_CALLBACK_PING
lcb_ping3()
Definition: couchbase.h:717
lcb_RESPBASE
Base response structure for callbacks.
Definition: couchbase.h:625
lcb_PINGSVC::status
lcb_PINGSTATUS status
status of the operation
Definition: couchbase.h:2537
LCB_CALLBACK_DIAG
@ LCB_CALLBACK_DIAG
lcb_diag()
Definition: couchbase.h:718
lcb_install_callback3
lcb_RESPCALLBACK lcb_install_callback3(lcb_t instance, int cbtype, lcb_RESPCALLBACK cb)