Couchbase C Client  3.2.2
Asynchronous C Client for Couchbase
utils.h
Go to the documentation of this file.
1 /* -*- Mode: C; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
2 /*
3  * Copyright 2011-2020 Couchbase, Inc.
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 
18 #ifndef LCB_UTILS_H
19 #define LCB_UTILS_H
20 
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31 
32 #define LCB_CONFIG_MCD_PORT 11210
33 #define LCB_CONFIG_MCD_SSL_PORT 11207
34 #define LCB_CONFIG_HTTP_PORT 8091
35 #define LCB_CONFIG_HTTP_SSL_PORT 18091
36 #define LCB_CONFIG_MCCOMPAT_PORT 11211
37 
52 #define LCB_CMD_SET_KEY(cmd, keybuf, keylen) LCB_KREQ_SIMPLE(&(cmd)->key, keybuf, keylen)
53 
65 typedef struct {
69  lcb_U32 cmdflags;
70 
79  lcb_U32 exptime;
80 
86  lcb_U64 cas;
87 
89  lcb_U32 cid;
90  const char *scope;
91  size_t nscope;
92  const char *collection;
93  size_t ncollection;
95  lcb_KEYBUF key;
96 
98  lcb_U32 timeout;
100  lcbtrace_SPAN *pspan;
101 } lcb_CMDCBFLUSH;
102 
103 typedef struct {
104  lcb_STATUS rc;
105  void *cookie;
106  lcb_U16 rflags;
107 } lcb_RESPCBFLUSH;
108 
131 LIBCOUCHBASE_API
132 lcb_STATUS lcb_cbflush3(lcb_INSTANCE *instance, void *cookie, const lcb_CMDCBFLUSH *cmd);
133 
212 enum lcb_timeunit_t {
213  LCB_TIMEUNIT_NSEC = 0,
217 };
219 
232 LIBCOUCHBASE_API
234 
243 LIBCOUCHBASE_API
245 
261 typedef void (*lcb_timings_callback)(lcb_INSTANCE *instance, const void *cookie, lcb_timeunit_t timeunit, lcb_U32 min,
262  lcb_U32 max, lcb_U32 total, lcb_U32 maxtotal);
263 
273 LIBCOUCHBASE_API
274 lcb_STATUS lcb_get_timings(lcb_INSTANCE *instance, const void *cookie, lcb_timings_callback callback);
277 typedef enum {
279  LCB_DUMP_VBCONFIG = 0x01,
281  LCB_DUMP_PKTINFO = 0x02,
283  LCB_DUMP_BUFINFO = 0x04,
285  LCB_DUMP_METRICS = 0x08,
287  LCB_DUMP_ALL = 0xff
289 
304 LIBCOUCHBASE_API
305 void lcb_dump(lcb_INSTANCE *instance, FILE *fp, lcb_U32 flags);
306 
308 struct lcb_histogram_st;
309 typedef struct lcb_histogram_st lcb_HISTOGRAM;
310 
316 LIBCOUCHBASE_API
317 lcb_HISTOGRAM *lcb_histogram_create(void);
318 
323 LIBCOUCHBASE_API
324 void lcb_histogram_destroy(lcb_HISTOGRAM *hg);
325 
332 LIBCOUCHBASE_API
333 void lcb_histogram_record(lcb_HISTOGRAM *hg, lcb_U64 duration);
334 
335 typedef void (*lcb_HISTOGRAM_CALLBACK)(const void *cookie, lcb_timeunit_t timeunit, lcb_U32 min, lcb_U32 max,
336  lcb_U32 total, lcb_U32 maxtotal);
337 
345 LIBCOUCHBASE_API
346 void lcb_histogram_read(const lcb_HISTOGRAM *hg, const void *cookie, lcb_HISTOGRAM_CALLBACK cb);
347 
358 LIBCOUCHBASE_API
359 void lcb_histogram_print(lcb_HISTOGRAM *hg, FILE *stream);
360 
366 /*
367  * @addtogroup lcb-collection-api
368  * @{
369  */
370 
371 typedef struct lcb_RESPGETMANIFEST_ lcb_RESPGETMANIFEST;
372 
373 LIBCOUCHBASE_API lcb_STATUS lcb_respgetmanifest_status(const lcb_RESPGETMANIFEST *resp);
374 LIBCOUCHBASE_API lcb_STATUS lcb_respgetmanifest_cookie(const lcb_RESPGETMANIFEST *resp, void **cookie);
375 LIBCOUCHBASE_API lcb_STATUS lcb_respgetmanifest_value(const lcb_RESPGETMANIFEST *resp, const char **json,
376  size_t *json_len);
377 
378 typedef struct lcb_CMDGETMANIFEST_ lcb_CMDGETMANIFEST;
379 
380 LIBCOUCHBASE_API lcb_STATUS lcb_cmdgetmanifest_create(lcb_CMDGETMANIFEST **cmd);
381 LIBCOUCHBASE_API lcb_STATUS lcb_cmdgetmanifest_destroy(lcb_CMDGETMANIFEST *cmd);
382 LIBCOUCHBASE_API lcb_STATUS lcb_cmdgetmanifest_timeout(lcb_CMDGETMANIFEST *cmd, uint32_t timeout);
383 LIBCOUCHBASE_API lcb_STATUS lcb_getmanifest(lcb_INSTANCE *instance, void *cookie, const lcb_CMDGETMANIFEST *cmd);
384 
385 typedef struct lcb_RESPGETCID_ lcb_RESPGETCID;
386 
387 LIBCOUCHBASE_API lcb_STATUS lcb_respgetcid_status(const lcb_RESPGETCID *resp);
388 LIBCOUCHBASE_API lcb_STATUS lcb_respgetcid_cookie(const lcb_RESPGETCID *resp, void **cookie);
389 LIBCOUCHBASE_API lcb_STATUS lcb_respgetcid_manifest_id(const lcb_RESPGETCID *resp, uint64_t *id);
390 LIBCOUCHBASE_API lcb_STATUS lcb_respgetcid_collection_id(const lcb_RESPGETCID *resp, uint32_t *id);
391 LIBCOUCHBASE_API lcb_STATUS lcb_respgetcid_scoped_collection(const lcb_RESPGETCID *resp, const char **name,
392  size_t *name_len);
393 
394 typedef struct lcb_CMDGETCID_ lcb_CMDGETCID;
395 
396 LIBCOUCHBASE_API lcb_STATUS lcb_cmdgetcid_create(lcb_CMDGETCID **cmd);
397 LIBCOUCHBASE_API lcb_STATUS lcb_cmdgetcid_destroy(lcb_CMDGETCID *cmd);
398 LIBCOUCHBASE_API lcb_STATUS lcb_cmdgetcid_scope(lcb_CMDGETCID *cmd, const char *scope, size_t scope_len);
399 LIBCOUCHBASE_API lcb_STATUS lcb_cmdgetcid_collection(lcb_CMDGETCID *cmd, const char *collection, size_t collection_len);
400 LIBCOUCHBASE_API lcb_STATUS lcb_cmdgetcid_timeout(lcb_CMDGETCID *cmd, uint32_t timeout);
401 
402 LIBCOUCHBASE_API lcb_STATUS lcb_getcid(lcb_INSTANCE *instance, void *cookie, const lcb_CMDGETCID *cmd);
420 typedef enum {
422  LCB_NODE_HTCONFIG = 0x01,
424  LCB_NODE_DATA = 0x02,
426  LCB_NODE_VIEWS = 0x04,
428  LCB_NODE_CONNECTED = 0x08,
429 
435 
443  LCB_NODE_HTCONFIG_ANY = 0x11
445 
448 #define LCB_GETNODE_UNAVAILABLE "invalid_host:0"
449 
492 LIBCOUCHBASE_API
493 const char *lcb_get_node(lcb_INSTANCE *instance, lcb_GETNODETYPE type, unsigned index);
494 
512 LIBCOUCHBASE_API
513 const char *lcb_get_keynode(lcb_INSTANCE *instance, const void *key, size_t nkey);
514 
523 LIBCOUCHBASE_API
524 lcb_S32 lcb_get_num_replicas(lcb_INSTANCE *instance);
525 
532 LIBCOUCHBASE_API
533 lcb_S32 lcb_get_num_nodes(lcb_INSTANCE *instance);
534 
552 LIBCOUCHBASE_API
553 const char *const *lcb_get_server_list(lcb_INSTANCE *instance);
554 
562 LIBCOUCHBASE_API
563 void *lcb_mem_alloc(lcb_SIZE size);
564 
566 LIBCOUCHBASE_API
567 void lcb_mem_free(void *ptr);
568 
578 LCB_INTERNAL_API
579 void lcb_run_loop(lcb_INSTANCE *instance);
580 
582 LCB_INTERNAL_API
583 void lcb_stop_loop(lcb_INSTANCE *instance);
584 
586 /* This returns the library's idea of time */
587 LCB_INTERNAL_API
588 lcb_U64 lcb_nstime(void);
589 
590 #ifdef __cplusplus
591 }
592 #endif
593 #endif /* LCB_UTILS_H */
LCB_INTERNAL_API void lcb_stop_loop(lcb_INSTANCE *instance)
void * lcb_mem_alloc(lcb_SIZE size)
Functions to allocate and free memory related to libcouchbase.
Dump various metrics information.
Definition: utils.h:290
Time is in nanoseconds.
Definition: utils.h:215
lcb_timeunit_t
Time units reported by lcb_get_timings()
Definition: utils.h:214
Dump information about each packet.
Definition: utils.h:286
Only return a node which is connected, or a node which is known to be up.
Definition: utils.h:438
Dump memory usage/reservation information about buffers.
Definition: utils.h:288
const char * lcb_get_node(lcb_INSTANCE *instance, lcb_GETNODETYPE type, unsigned index)
Return a string of host:port for a node of the given type.
lcb_STATUS lcb_get_timings(lcb_INSTANCE *instance, const void *cookie, lcb_timings_callback callback)
Get the timings histogram
const char *const * lcb_get_server_list(lcb_INSTANCE *instance)
Get a list of nodes in the cluster
Dump everything.
Definition: utils.h:292
void lcb_histogram_record(lcb_HISTOGRAM *hg, lcb_U64 duration)
Time is in microseconds.
Definition: utils.h:216
lcb_STATUS
Error codes returned by the library.
Definition: error.h:210
lcb_STATUS lcb_disable_timings(lcb_INSTANCE *instance)
Stop recording (and release all resources from previous measurements) timing metrics.
LCB_INTERNAL_API void lcb_run_loop(lcb_INSTANCE *instance)
Dump the raw vbucket configuration.
Definition: utils.h:284
lcb_DUMPFLAGS
Definition: utils.h:282
void lcb_histogram_read(const lcb_HISTOGRAM *hg, const void *cookie, lcb_HISTOGRAM_CALLBACK cb)
Equivalent to LCB_NODE_HTCONFIG|LCB_NODE_CONNECTED
Definition: utils.h:447
Get a view (CAPI) node.
Definition: utils.h:436
Time is in milliseconds.
Definition: utils.h:217
Equivalent to LCB_NODE_HTCONFIG|LCB_NODE_NEVERNULL.
Definition: utils.h:453
lcb_S32 lcb_get_num_nodes(lcb_INSTANCE *instance)
Get the number of the nodes in the cluster
lcb_S32 lcb_get_num_replicas(lcb_INSTANCE *instance)
Get the number of the replicas in the cluster
void lcb_histogram_destroy(lcb_HISTOGRAM *hg)
struct lcb_st lcb_INSTANCE
Library handle representing a connection to a cluster and its data buckets.
Definition: couchbase.h:35
const char * lcb_get_keynode(lcb_INSTANCE *instance, const void *key, size_t nkey)
Get the target server for a given key.
void(* lcb_timings_callback)(lcb_INSTANCE *instance, const void *cookie, lcb_timeunit_t timeunit, lcb_U32 min, lcb_U32 max, lcb_U32 total, lcb_U32 maxtotal)
The following function is called for each bucket in the timings histogram when you call lcb_get_timin...
Definition: utils.h:265
lcb_HISTOGRAM * lcb_histogram_create(void)
LCB_INTERNAL_API lcb_U64 lcb_nstime(void)
Get a data (memcached) node.
Definition: utils.h:434
Get an HTTP configuration (Rest API) node.
Definition: utils.h:432
lcb_STATUS lcb_enable_timings(lcb_INSTANCE *instance)
Start recording timing metrics for the different operations.
Specifying this flag adds additional semantics which instruct the library to search additional resour...
Definition: utils.h:444
Time is in seconds.
Definition: utils.h:218
void lcb_histogram_print(lcb_HISTOGRAM *hg, FILE *stream)
Print the histogram to the specified FILE.
lcb_GETNODETYPE
Type of node to retrieve for the lcb_get_node() function.
Definition: utils.h:430
void lcb_dump(lcb_INSTANCE *instance, FILE *fp, lcb_U32 flags)
Write a textual dump to a file.
Common request header for all keys.
Definition: kvbuf.h:58
lcb_STATUS lcb_cbflush3(lcb_INSTANCE *instance, void *cookie, const lcb_CMDCBFLUSH *cmd)
void lcb_mem_free(void *ptr)
Use this to free memory allocated with lcb_mem_alloc.