Couchbase C Client  2.10.7
Asynchronous C Client for Couchbase
Waiting

Detailed Description

Functions for synchronous I/O execution.

The lcb_wait() family of functions allow to control when the library sends the operations to the cluster and waits for their execution.

It is also possible to use non-blocking I/O with the library

Functions

lcb_error_t lcb_wait (lcb_t instance)
 Wait for the execution of all batched requests. More...
 
lcb_error_t lcb_tick_nowait (lcb_t instance)
 
void lcb_wait3 (lcb_t instance, lcb_WAITFLAGS flags)
 Wait for completion of scheduled operations. More...
 
void lcb_breakout (lcb_t instance)
 Forcefully break from the event loop. More...
 
int lcb_is_waiting (lcb_t instance)
 Check if instance is blocked in the event loop. More...
 

Enumerations

enum  lcb_WAITFLAGS
 Flags for lcb_wait3() More...
 

Function Documentation

◆ lcb_wait()

lcb_error_t lcb_wait ( lcb_t  instance)

Wait for the execution of all batched requests.

A batched request is any request which requires network I/O. This includes most of the APIs. You should not use this API if you are integrating with an asynchronous event loop (i.e. one where your application code is invoked asynchronously via event loops).

This function will block the calling thread until either

  • All operations have been completed
  • lcb_breakout() is explicitly called
Parameters
instancethe instance containing the requests
Returns
whether the wait operation failed, or LCB_SUCCESS
Stability
Committed:
Examples
example/analytics/analytics.c, example/crypto/openssl_symmetric_decrypt.c, example/crypto/openssl_symmetric_encrypt.c, example/fts/fts.c, example/minimal/minimal.c, example/minimal/query.c, example/observe/durability.c, example/observe/observe.c, example/subdoc/subdoc-xattrs.c, example/tracing/tracing.c, and example/tracing/views.c.

◆ lcb_tick_nowait()

lcb_error_t lcb_tick_nowait ( lcb_t  instance)
Stability
Volatile:
This function will cause a single "tick" in the underlying event loop, causing operations whose I/O can be executed immediately to be sent to the server.

Like lcb_wait(), callbacks for operations may be delivered here, however some operations may be left incomplete if their I/O could not be processed immediately. This function is intended as an optimization for large batches of operations - so that some I/O can be completed during the batching process itself, and only the remainder of those operations (which would have blocked) will be completed with lcb_wait() (which should be invoked after the batch).

This function is mainly useful if there is a significant delay in time between each scheduling function, in which I/O may be completed during these gaps (thereby emptying the socket's kernel write buffer, and allowing for new operations to be added after the interval). Calling this function for batches where all data is available up-front may actually make things slower.

Warning
You must call lcb_wait() at least one after any batch of operations to ensure they have been completed. This function is provided as an optimization only.
Returns
LCB_CLIENT_FEATURE_UNAVAILABLE if the event loop does not support the "tick" mode.

◆ lcb_wait3()

void lcb_wait3 ( lcb_t  instance,
lcb_WAITFLAGS  flags 
)

Wait for completion of scheduled operations.

Stability
Committed:
Parameters
instancethe instance
flagsflags to modify the behavior of lcb_wait(). Pass 0 to obtain behavior identical to lcb_wait().

◆ lcb_breakout()

void lcb_breakout ( lcb_t  instance)

Forcefully break from the event loop.

You may call this function from within any callback to signal to the library that it return control to the function calling lcb_wait() as soon as possible. Note that if there are pending functions which have not been processed, you are responsible for calling lcb_wait() a second time.

Parameters
instancethe instance to run the event loop for.
Stability
Committed:

◆ lcb_is_waiting()

int lcb_is_waiting ( lcb_t  instance)

Check if instance is blocked in the event loop.

Parameters
instancethe instance to run the event loop for.
Returns
non-zero if nobody is waiting for IO interaction
Stability
Uncommitted:

Enumeration Type Documentation

◆ lcb_WAITFLAGS

Flags for lcb_wait3()

Enumerator
LCB_WAIT_DEFAULT 

Behave like the old lcb_wait()

LCB_WAIT_NOCHECK 

Do not check pending operations before running the event loop.

By default lcb_wait() will traverse the server list to check if any operations are pending, and if nothing is pending the function will return without running the event loop. This is usually not necessary for applications which already only call lcb_wait() when they know they have scheduled at least one command.