Couchbase C Client  2.10.6
Asynchronous C Client for Couchbase
Network I/O

Detailed Description

I/O Integration comes in two flavors:

(E)vent/Poll Based Integration
This system is based upon the interfaces exposed by the poll(2) and select(2) calls found in POSIX-based systems and are wrapped by systems such as libevent and libev. At their core is the notion that a socket may be polled for readiness (either readiness for reading or readiness for writing). When a socket is deemed ready, a callback is invoked indicating which events took place.
(C)ompletion/Operation/Buffer Based Integration
This system is based upon the interfaces exposed in the Win32 API where I/O is done in terms of operations which are awaiting completion. As such buffers are passed into the core, and the application is notified when the operation on those buffers (either read into a buffer, or write from a buffer) has been completed.

Modules

 libevent
 libev integration
 
 libev
 libev integration
 
 libuv
 libuv integration
 

Functions

void lcb_iops_wire_bsd_impl2 (lcb_bsd_procs *procs, int version)
 
lcb_error_t lcb_create_io_ops (lcb_io_opt_t *op, const struct lcb_create_io_ops_st *options)
 Create a new instance of one of the library-supplied io ops types. More...
 
lcb_error_t lcb_destroy_io_ops (lcb_io_opt_t op)
 Destroy the plugin handle created by lcb_create_io_ops() More...
 

Macros

#define LCB_IOV_LAYOUT_UIO
 Defined if the lcb_IOV structure conforms to struct iovec
 
#define LCB_IOPS_DEPRECATED(X)
 
#define LCB_IOPS_BASE_FIELDS
 
#define LCB_IOPROCS_VERSION
 This number is bumped up each time a new field is added to any of the function tables. More...
 
#define LCB_IOPS_BASEFLD(iops, fld)
 
#define LCB_IOPS_ERRNO(iops)
 

Typedefs

typedef int lcb_socket_t
 Type representing the native socket type of the operating system.
 
typedef void(* lcb_ioE_callback) (lcb_socket_t sock, short events, void *uarg)
 Callback invoked for all poll-like events. More...
 
typedef void(* lcb_io_start_fn) (lcb_io_opt_t iops)
 Start the event loop. More...
 
typedef void(* lcb_io_tick_fn) (lcb_io_opt_t iops)
 Run a single iteration of the event loop without blocking. More...
 
typedef void(* lcb_io_stop_fn) (lcb_io_opt_t iops)
 Pause the event loop. More...
 
typedef void(* lcb_io_error_cb) (lcb_sockdata_t *socket))
 
typedef void(* lcb_io_procs_fn) (int version, lcb_loop_procs *loop_procs, lcb_timer_procs *timer_procs, lcb_bsd_procs *bsd_procs, lcb_ev_procs *ev_procs, lcb_completion_procs *completion_procs, lcb_iomodel_t *iomodel)
 
typedef void(* lcb__iops3fndummy) (void)
 
typedef lcb_error_t(* lcb_io_create_fn) (int version, lcb_io_opt_t *io, void *cookie)
 Signature for a loadable plugin's IOPS initializer. More...
 

Enumerations

enum  lcb_iomodel_t
 Enumeration defining the I/O model. More...
 
enum  lcb_io_ops_type_t
 Built-in I/O plugins. More...
 

Timer Callbacks

typedef void *(* lcb_io_timer_create_fn) (lcb_io_opt_t iops)
 Create a new timer object. More...
 
typedef void(* lcb_io_timer_destroy_fn) (lcb_io_opt_t iops, void *timer)
 Destroy a timer handler. More...
 
typedef void(* lcb_io_timer_cancel_fn) (lcb_io_opt_t iops, void *timer)
 Cancel a pending timer callback. More...
 
typedef int(* lcb_io_timer_schedule_fn) (lcb_io_opt_t iops, void *timer, lcb_U32 usecs, void *uarg, lcb_ioE_callback callback)
 Schedule a callback to be invoked within a given interval. More...
 

Event Handle Callbacks

typedef void *(* lcb_ioE_event_create_fn) (lcb_io_opt_t iops)
 Create a new event handle. More...
 
typedef void(* lcb_ioE_event_destroy_fn) (lcb_io_opt_t iops, void *event)
 Destroy an event handle. More...
 
typedef void(* lcb_ioE_event_cancel_fn) (lcb_io_opt_t iops, lcb_socket_t sock, void *event)
 Cancel pending callbacks and unwatch a handle. More...
 
typedef int(* lcb_ioE_event_watch_fn) (lcb_io_opt_t iops, lcb_socket_t socket, void *event, short evflags, void *uarg, lcb_ioE_callback callback)
 Associate an event with a socket, requesting notification when one of the events specified in 'flags' becomes available on the socket. More...
 
#define LCB_READ_EVENT
 Data is available for reading.
 
#define LCB_WRITE_EVENT
 Data can be written.
 
#define LCB_ERROR_EVENT
 Exceptional condition ocurred on socket.
 
#define LCB_RW_EVENT
 

BSD-API I/O Routines

typedef lcb_SSIZE(* lcb_ioE_recv_fn) (lcb_io_opt_t iops, lcb_socket_t sock, void *target_buf, lcb_SIZE buflen, int _unused_flags)
 Receive data into a single buffer. More...
 
typedef lcb_SSIZE(* lcb_ioE_send_fn) (lcb_io_opt_t iops, lcb_socket_t sock, const void *srcbuf, lcb_SIZE buflen, int _ignored)
 Send data from a single buffer. More...
 
typedef lcb_SSIZE(* lcb_ioE_recvv_fn) (lcb_io_opt_t iops, lcb_socket_t sock, lcb_IOV *iov, lcb_SIZE niov)
 Read data into a series of buffers. More...
 
typedef lcb_SSIZE(* lcb_ioE_sendv_fn) (lcb_io_opt_t iops, lcb_socket_t sock, lcb_IOV *iov, lcb_SIZE niov)
 Write data from multiple buffers. More...
 
typedef lcb_socket_t(* lcb_ioE_socket_fn) (lcb_io_opt_t iops, int domain, int type, int protocol)
 Create a new socket. More...
 
typedef int(* lcb_ioE_connect_fn) (lcb_io_opt_t iops, lcb_socket_t sock, const struct sockaddr *dst, unsigned int addrlen)
 Connect a created socket. More...
 
typedef int(* lcb_ioE_bind_fn) (lcb_io_opt_t iops, lcb_socket_t sock, const struct sockaddr *srcaddr, unsigned int addrlen)
 
typedef int(* lcb_ioE_listen_fn) (lcb_io_opt_t iops, lcb_socket_t bound_sock, unsigned int queuelen)
 
typedef lcb_socket_t(* lcb_ioE_accept_fn) (lcb_io_opt_t iops, lcb_socket_t lsnsock)
 
typedef void(* lcb_ioE_close_fn) (lcb_io_opt_t iops, lcb_socket_t sock)
 Close a socket. More...
 
typedef int(* lcb_ioE_chkclosed_fn) (lcb_io_opt_t iops, lcb_socket_t sock, int flags)
 Check if a socket has been closed or not. More...
 
typedef int(* lcb_ioE_cntl_fn) (lcb_io_opt_t iops, lcb_socket_t sock, int mode, int option, void *arg)
 Execute a specificied operation on a socket. More...
 
#define LCB_IO_SOCKCHECK_PEND_IS_ERROR
 While checking the socket, treat pending data as an error. More...
 
#define LCB_IO_SOCKCHECK_STATUS_CLOSED
 
#define LCB_IO_SOCKCHECK_STATUS_OK
 
#define LCB_IO_SOCKCHECK_STATUS_UNKNOWN
 
#define LCB_IO_CNTL_GET
 For use with io{E,C}_cntl_fn, indicates the setting should be retrieved.
 
#define LCB_IO_CNTL_SET
 For use with lcb_io{E,C}_cntl_fn`, indicates the setting should be modified.
 
#define LCB_IO_CNTL_TCP_NODELAY
 Disable Nagle's algorithm (use an int)
 
#define LCB_IO_CNTL_TCP_KEEPALIVE
 Enable/Disable TCP Keepalive.
 

Completion Routines

typedef lcb_sockdata_t *(* lcb_ioC_socket_fn) (lcb_io_opt_t iops, int domain, int type, int protocol)
 Create a completion socket handle. More...
 
typedef void(* lcb_io_connect_cb) (lcb_sockdata_t *socket, int status)
 Callback to be invoked upon a connection result. More...
 
typedef int(* lcb_ioC_connect_fn) (lcb_io_opt_t iops, lcb_sockdata_t *sd, const struct sockaddr *dst, unsigned int naddr, lcb_io_connect_cb callback)
 Request a connection for a socket. More...
 
typedef void() lcb_ioC_serve_callback(lcb_sockdata_t *sd_server, lcb_sockdata_t *sd_client, int status)
 Callback invoked when a new client connection has been established. More...
 
typedef int(* lcb_ioC_serve_fn) (lcb_io_opt_t iops, lcb_sockdata_t *server_socket, const struct sockaddr *listen_addr, lcb_ioC_serve_callback callback)
 Specify that the socket start accepting connections. More...
 
typedef int(* lcb_ioC_nameinfo_fn) (lcb_io_opt_t iops, lcb_sockdata_t *sock, struct lcb_nameinfo_st *ni)
 Request address information on a connected socket. More...
 
typedef void(* lcb_ioC_read_callback) (lcb_sockdata_t *sd, lcb_SSIZE nread)
 
typedef int(* lcb_ioC_read_fn) (lcb_io_opt_t, lcb_sockdata_t *, lcb_ioC_read_callback)
 
typedef lcb_io_writebuf_t *(* lcb_ioC_wballoc_fn) (lcb_io_opt_t, lcb_sockdata_t *)
 
typedef void(* lcb_ioC_wbfree_fn) (lcb_io_opt_t, lcb_sockdata_t *, lcb_io_writebuf_t *)
 
typedef void(* lcb_ioC_write_callback) (lcb_sockdata_t *, lcb_io_writebuf_t *, int)
 
typedef int(* lcb_ioC_write_fn) (lcb_io_opt_t, lcb_sockdata_t *, lcb_io_writebuf_t *, lcb_ioC_write_callback)
 
typedef void(* lcb_ioC_write2_callback) (lcb_sockdata_t *sd, int status, void *arg)
 Callback received when a buffer has been flushed. More...
 
typedef int(* lcb_ioC_write2_fn) (lcb_io_opt_t iops, lcb_sockdata_t *sd, lcb_IOV *iov, lcb_SIZE niov, void *uarg, lcb_ioC_write2_callback callback)
 Schedule a flush of a series of buffers to the network. More...
 
typedef void(* lcb_ioC_read2_callback) (lcb_sockdata_t *sd, lcb_SSIZE nread, void *arg)
 Callback invoked when a read has been completed. More...
 
typedef int(* lcb_ioC_read2_fn) (lcb_io_opt_t iops, lcb_sockdata_t *sd, lcb_IOV *iov, lcb_SIZE niov, void *uarg, lcb_ioC_read2_callback callback)
 Schedule a read from the network. More...
 
typedef unsigned int(* lcb_ioC_close_fn) (lcb_io_opt_t iops, lcb_sockdata_t *sd)
 Asynchronously shutdown the socket. More...
 
typedef int(* lcb_ioC_chkclosed_fn) (lcb_io_opt_t iops, lcb_sockdata_t *sd, int flags)
 This is the completion variant of lcb_ioE_chkclosed_fn. More...
 
typedef int(* lcb_ioC_cntl_fn) (lcb_io_opt_t iops, lcb_sockdata_t *sd, int mode, int option, void *arg)
 
#define lcb_io_read_cb
 
#define lcb_io_write_cb
 

Function Documentation

◆ lcb_iops_wire_bsd_impl2()

void lcb_iops_wire_bsd_impl2 ( lcb_bsd_procs procs,
int  version 
)
Stability
Volatile:

This is an alternative to copying the 'bsdio-inl.c' file around. It is designed specifically for the lcb_io_procs_fn function and will do the job of applying the current runtime version of the default event-based I/O implementation.

e.g.

static void getprocs_impl(int version, lcb_loop_procs *loop_procs,
lcb_timer_procs *timer_procs, lcb_bsd_procs *bsd_procs,
lcb_ev_procs *ev_procs, lcb_completion_procs *completion_procs,
lcb_iomodel_t *iomodel) {
// do stuff normally
// ..
// install the default I/O handlers:
lcb_iops_wire_bsd_impl2(bsd_procs, version);

Use this function with care, and understand the implications between using this API call and embedding the bsdio-inl.c source file. Specifically:

  • If your application is using an older version of the library, this implementation may contain bugs not present in the version you compiled against (and an embedded version may be newer)
  • If your application is using a newer version, there may be some additional I/O functions which you may wish to wrap or rather not implement at all, but will be implemented if you call this function.

◆ lcb_create_io_ops()

lcb_error_t lcb_create_io_ops ( lcb_io_opt_t *  op,
const struct lcb_create_io_ops_st options 
)

Create a new instance of one of the library-supplied io ops types.

This function should only be used if you wish to override/customize the default I/O plugin behavior; for example to select a specific implementation (e.g. always for the select plugin) and/or to integrate a builtin plugin with your own application (e.g. pass an existing event_base structure to the libevent plugin).

If you do use this function, then you must call lcb_destroy_io_ops() on the plugin handle once it is no longer required (and no instance is using it).

Whether a single lcb_io_opt_t may be used by multiple instances at once is dependent on the specific implementation, but as a general rule it should be assumed to be unsafe.

Parameters
[out]opThe newly created io ops structure
optionsHow to create the io ops structure
Returns
LCB_SUCCESS on success
Stability
Uncommitted:
Examples
example/libeventdirect/main.c.

◆ lcb_destroy_io_ops()

lcb_error_t lcb_destroy_io_ops ( lcb_io_opt_t  op)

Destroy the plugin handle created by lcb_create_io_ops()

Parameters
opops structure
Returns
LCB_SUCCESS on success
Stability
Uncommitted:
Examples
example/libeventdirect/main.c.

Data Structure Documentation

◆ lcb_IOV

struct lcb_IOV

structure indicating a buffer and its size

This is compatible with a struct iovec on Unix and a WSABUF structure on Windows. It has an iov_base field which is the base pointer and an iov_len field which is the length of the buffer.

Data Fields
void * iov_base
size_t iov_len

◆ lcb_nameinfo_st

struct lcb_nameinfo_st

structure describing a connected socket's endpoints

Data Fields
struct lcb_nameinfo_st local
struct lcb_nameinfo_st remote

◆ lcb_buf_info

struct lcb_buf_info
Deprecated:
Ringbuffers are no longer used this way by the library for I/O
Data Fields
char * root
lcb_SIZE size
struct ringbuffer_st * ringbuffer
struct lcb_iovec_st iov[2]

◆ lcb_sockdata_t

struct lcb_sockdata_t

Socket handle for completion-based I/O.

The sockdata structure is analoguous to an lcb_socket_t returned by the E-model I/O.

Data Fields
lcb_socket_t socket System socket, for informational purposes.
lcb_io_opt_t parent Parent I/O context.
struct lcbio_SOCKET * lcbconn Internal socket equivalent.
int closed
Deprecated:
No longer used by the library
int is_reading Internally used by lcbio.
struct lcb_buf_info read_buffer
Deprecated:
No longer used by the library

◆ lcb_io_writebuf_t

struct lcb_io_writebuf_t
Data Fields
struct lcb_io_opt_st * parent
struct lcb_buf_info buffer

◆ lcb_timer_procs

struct lcb_timer_procs

Common functions for starting and stopping timers.

Data Fields
lcb_io_timer_create_fn create
lcb_io_timer_destroy_fn destroy
lcb_io_timer_cancel_fn cancel
lcb_io_timer_schedule_fn schedule

◆ lcb_loop_procs

struct lcb_loop_procs

Common functions for starting and stopping the event loop.

Data Fields
lcb_io_start_fn start
lcb_io_stop_fn stop
lcb_io_tick_fn tick

◆ lcb_bsd_procs

struct lcb_bsd_procs

Functions wrapping the Berkeley Socket API.

Data Fields
lcb_ioE_socket_fn socket0
lcb_ioE_connect_fn connect0
lcb_ioE_recv_fn recv
lcb_ioE_recvv_fn recvv
lcb_ioE_send_fn send
lcb_ioE_sendv_fn sendv
lcb_ioE_close_fn close
lcb_ioE_bind_fn bind
lcb_ioE_listen_fn listen
lcb_ioE_accept_fn accept
lcb_ioE_chkclosed_fn is_closed
lcb_ioE_cntl_fn cntl

◆ lcb_ev_procs

struct lcb_ev_procs

Functions handling socket watcher events.

Data Fields
lcb_ioE_event_create_fn create
lcb_ioE_event_destroy_fn destroy
lcb_ioE_event_cancel_fn cancel
lcb_ioE_event_watch_fn watch

◆ lcb_completion_procs

struct lcb_completion_procs

Functions for completion-based I/O.

Data Fields
lcb_ioC_socket_fn socket
lcb_ioC_close_fn close
lcb_ioC_read_fn read
lcb_ioC_connect_fn connect
lcb_ioC_wballoc_fn wballoc
lcb_ioC_wbfree_fn wbfree
lcb_ioC_write_fn write
lcb_ioC_write2_fn write2
lcb_ioC_read2_fn read2
lcb_ioC_serve_fn serve
lcb_ioC_nameinfo_fn nameinfo
lcb_ioC_chkclosed_fn is_closed
lcb_ioC_cntl_fn cntl

◆ lcb_IOCREATEOPTS_BUILTIN

struct lcb_IOCREATEOPTS_BUILTIN

IO Creation for builtin plugins.

Data Fields
lcb_io_ops_type_t type The predefined type you want to create.
void * cookie Plugin-specific argument.

◆ lcb_create_io_ops_st

struct lcb_create_io_ops_st
Data Fields
int version
union lcb_create_io_ops_st v

Macro Definition Documentation

◆ LCB_IO_SOCKCHECK_PEND_IS_ERROR

#define LCB_IO_SOCKCHECK_PEND_IS_ERROR

While checking the socket, treat pending data as an error.

This flag will be missing if the socket participates in a protocol where unsolicited data is possible.

Currently Couchbase does not provide such a protocol (at least not one where sockets are placed in a pool), but it may in the future.

This may be passed as a flags option to lcb_ioE_chkclosed_fn

◆ LCB_IOPROCS_VERSION

#define LCB_IOPROCS_VERSION

This number is bumped up each time a new field is added to any of the function tables.

This number is backwards compatible (i.e. version 3 contains all the fields of version 2, and some additional ones)

Typedef Documentation

◆ lcb_ioE_callback

typedef void(* lcb_ioE_callback) (lcb_socket_t sock, short events, void *uarg)

Callback invoked for all poll-like events.

Parameters
sockthe socket associated with the event
eventsthe events which activated this callback. This is set of bits comprising of LCB_READ_EVENT, LCB_WRITE_EVENT, and LCB_ERROR_EVENT
uarga user-defined pointer passed to the lcb_ioE_event_watch_fn routine.

◆ lcb_io_timer_create_fn

typedef void*(* lcb_io_timer_create_fn) (lcb_io_opt_t iops)

Create a new timer object.

Parameters
iopsthe io structure
Returns
an opaque timer handle. The timer shall remain inactive and shall be destroyed via the lcb_io_timer_destroy_fn routine.

◆ lcb_io_timer_destroy_fn

typedef void(* lcb_io_timer_destroy_fn) (lcb_io_opt_t iops, void *timer)

Destroy a timer handler.

Destroy a timer previously created with lcb_io_timer_create_fn

Parameters
iopsthe io structure
timerthe opaque handle The timer must have already been cancelled via lcb_io_timer_cancel_fn

◆ lcb_io_timer_cancel_fn

typedef void(* lcb_io_timer_cancel_fn) (lcb_io_opt_t iops, void *timer)

Cancel a pending timer callback.

Cancel and unregister a pending timer. If the timer has already fired, this does nothing. If the timer has not yet fired, the callback shall not be delivered.

Parameters
iopsthe I/O structure
timerthe timer to cancel.

◆ lcb_io_timer_schedule_fn

typedef int(* lcb_io_timer_schedule_fn) (lcb_io_opt_t iops, void *timer, lcb_U32 usecs, void *uarg, lcb_ioE_callback callback)

Schedule a callback to be invoked within a given interval.

Schedule a timer to be fired within usec microseconds from now

Parameters
iopsthe I/O structure
timera timer previously created with timer_create
usecsthe timer interval
uargthe user-defined pointer to be passed in the callback
callbackthe callback to invoke

◆ lcb_ioE_event_create_fn

typedef void*(* lcb_ioE_event_create_fn) (lcb_io_opt_t iops)

Create a new event handle.

An event object may be used to monitor a socket for given I/O readiness events

Parameters
iopsthe I/O structure.
Returns
a new event handle. The handle may then be associated with a socket and watched (via lcb_ioE_event_watch_fn) for I/O readiness.

◆ lcb_ioE_event_destroy_fn

typedef void(* lcb_ioE_event_destroy_fn) (lcb_io_opt_t iops, void *event)

Destroy an event handle.

Destroy an event object. The object must not be active.

Parameters
iopsthe I/O structure
eventthe event to free

◆ lcb_ioE_event_cancel_fn

typedef void(* lcb_ioE_event_cancel_fn) (lcb_io_opt_t iops, lcb_socket_t sock, void *event)

Cancel pending callbacks and unwatch a handle.

Deprecated:
lcb_ioE_event_watch_fn() should be used with 0 for events
Parameters
iopsthe I/O structure
sockthe socket associated with the event
eventthe opaque event object

This function may be called multiple times and shall not fail even if the event is already inactive.

◆ lcb_ioE_event_watch_fn

typedef int(* lcb_ioE_event_watch_fn) (lcb_io_opt_t iops, lcb_socket_t socket, void *event, short evflags, void *uarg, lcb_ioE_callback callback)

Associate an event with a socket, requesting notification when one of the events specified in 'flags' becomes available on the socket.

Parameters
iopsthe IO context
socketthe socket to watch
eventthe event to associate with the socket. If this parameter is
evflagsa bitflag of events to watch. This is one of LCB_READ_EVENT, LCB_WRITE_EVENT, or LCB_RW_EVENT. If this value is 0 then existing events shall be cancelled on the socket.

Note that the callback may also receive LCB_ERROR_EVENT but this cannot be requested as an event to watch for.

Parameters
uarga user defined pointer to be passed to the callback
callbackthe callback to invoke when one of the events becomes ready.
Attention
It shall be legal to call this routine multiple times without having to call the lcb_ioE_event_cancel_fn(). The cancel function should in fact be implemented via passing a 0 to the evflags parameter, effectively clearing the event.

◆ lcb_ioE_recv_fn

typedef lcb_SSIZE(* lcb_ioE_recv_fn) (lcb_io_opt_t iops, lcb_socket_t sock, void *target_buf, lcb_SIZE buflen, int _unused_flags)

Receive data into a single buffer.

See also
recv(2) socket API call.

◆ lcb_ioE_send_fn

typedef lcb_SSIZE(* lcb_ioE_send_fn) (lcb_io_opt_t iops, lcb_socket_t sock, const void *srcbuf, lcb_SIZE buflen, int _ignored)

Send data from a single buffer.

See also
send(2) on POSIX

◆ lcb_ioE_recvv_fn

typedef lcb_SSIZE(* lcb_ioE_recvv_fn) (lcb_io_opt_t iops, lcb_socket_t sock, lcb_IOV *iov, lcb_SIZE niov)

Read data into a series of buffers.

See also
the recvmsg(2) function on POSIX

◆ lcb_ioE_sendv_fn

typedef lcb_SSIZE(* lcb_ioE_sendv_fn) (lcb_io_opt_t iops, lcb_socket_t sock, lcb_IOV *iov, lcb_SIZE niov)

Write data from multiple buffers.

See also
the sendmsg(2) function on POSIX

◆ lcb_ioE_socket_fn

typedef lcb_socket_t(* lcb_ioE_socket_fn) (lcb_io_opt_t iops, int domain, int type, int protocol)

Create a new socket.

See also
socket(2) on POSIX

◆ lcb_ioE_connect_fn

typedef int(* lcb_ioE_connect_fn) (lcb_io_opt_t iops, lcb_socket_t sock, const struct sockaddr *dst, unsigned int addrlen)

Connect a created socket.

See also
connect(2) on POSIX

◆ lcb_ioE_bind_fn

typedef int(* lcb_ioE_bind_fn) (lcb_io_opt_t iops, lcb_socket_t sock, const struct sockaddr *srcaddr, unsigned int addrlen)
Stability
Internal:

◆ lcb_ioE_listen_fn

typedef int(* lcb_ioE_listen_fn) (lcb_io_opt_t iops, lcb_socket_t bound_sock, unsigned int queuelen)
Stability
Internal:

◆ lcb_ioE_accept_fn

typedef lcb_socket_t(* lcb_ioE_accept_fn) (lcb_io_opt_t iops, lcb_socket_t lsnsock)
Stability
Internal:

◆ lcb_ioE_close_fn

typedef void(* lcb_ioE_close_fn) (lcb_io_opt_t iops, lcb_socket_t sock)

Close a socket.

See also
close(2) and shutdown(2)

◆ lcb_ioE_chkclosed_fn

typedef int(* lcb_ioE_chkclosed_fn) (lcb_io_opt_t iops, lcb_socket_t sock, int flags)

Check if a socket has been closed or not.

This is used to check a socket's state after a period of inactivity.

Parameters
iopsThe iops
sockThe socket to check
flagsA bit set of options.
Returns
A value greater than 0 if the socket is closed, 0 if the socket has not been closed, or a negative number, if the status could not be determined within the given constraints (for example, if flags did not specify LCB_IO_SOCKCHECK_PEND_IS_ERROR, and the implementation does not have a way to check status otherwise.
Since
2.4.4

◆ lcb_ioE_cntl_fn

typedef int(* lcb_ioE_cntl_fn) (lcb_io_opt_t iops, lcb_socket_t sock, int mode, int option, void *arg)

Execute a specificied operation on a socket.

Parameters
iopsThe iops
sockThe socket
modeThe mode, can be LCB_IO_CNTL_GET or LCB_IO_CNTL_SET
optionThe option to access
[in,out]argthe argument for the option
Returns
zero on success, nonzero on failure.

◆ lcb_ioC_socket_fn

typedef lcb_sockdata_t*(* lcb_ioC_socket_fn) (lcb_io_opt_t iops, int domain, int type, int protocol)

Create a completion socket handle.

Create an opaque socket handle

Parameters
iopsthe IO context
domainsocket address family, e.g. AF_INET
typethe transport type, e.g. SOCK_STREAM
protocolthe IP protocol, e.g. IPPROTO_TCP
Returns
a socket pointer or NULL on failure.

◆ lcb_io_connect_cb

typedef void(* lcb_io_connect_cb) (lcb_sockdata_t *socket, int status)

Callback to be invoked upon a connection result.

Callback invoked for a connection result.

Parameters
socketthe socket which is being connected
statusthe status. 0 for success, nonzero on failure

◆ lcb_ioC_connect_fn

typedef int(* lcb_ioC_connect_fn) (lcb_io_opt_t iops, lcb_sockdata_t *sd, const struct sockaddr *dst, unsigned int naddr, lcb_io_connect_cb callback)

Request a connection for a socket.

Parameters
iopsthe IO context
sdthe socket pointer
dstthe address to connect to
naddrthe size of the address len, e.g. sizeof(struct sockaddr_in)
callbackthe callback to invoke when the connection status is determined
Returns
0 on success, nonzero if a connection could not be scheduled.

◆ lcb_ioC_serve_callback

typedef void() lcb_ioC_serve_callback(lcb_sockdata_t *sd_server, lcb_sockdata_t *sd_client, int status)

Callback invoked when a new client connection has been established.

Parameters
sd_serverthe server listen socket
sd_clientthe new client socket
statusif there was an error accepting (in this case, sd_client is NULL

◆ lcb_ioC_serve_fn

typedef int(* lcb_ioC_serve_fn) (lcb_io_opt_t iops, lcb_sockdata_t *server_socket, const struct sockaddr *listen_addr, lcb_ioC_serve_callback callback)

Specify that the socket start accepting connections.

This should be called on a newly created non-connected socket

Parameters
iopsthe I/O context
server_socketthe socket used to listen with
sockaddrthe local address for listening
callbackthe callback to invoke for each new connection

◆ lcb_ioC_nameinfo_fn

typedef int(* lcb_ioC_nameinfo_fn) (lcb_io_opt_t iops, lcb_sockdata_t *sock, struct lcb_nameinfo_st *ni)

Request address information on a connected socket.

Parameters
iopsthe I/O context
sockthe socket from which to retrieve information
nia nameinfo structure to populate with the relevant details

◆ lcb_ioC_read_callback

typedef void(* lcb_ioC_read_callback) (lcb_sockdata_t *sd, lcb_SSIZE nread)

◆ lcb_ioC_read_fn

typedef int(* lcb_ioC_read_fn) (lcb_io_opt_t, lcb_sockdata_t *, lcb_ioC_read_callback)
Deprecated:
See lcb_ioC_read2_fn().

Wrapped if not implemented

◆ lcb_ioC_wballoc_fn

typedef lcb_io_writebuf_t*(* lcb_ioC_wballoc_fn) (lcb_io_opt_t, lcb_sockdata_t *)
Deprecated:
See lcb_ioC_write2_fn().

Wrapped if not implemented

◆ lcb_ioC_wbfree_fn

typedef void(* lcb_ioC_wbfree_fn) (lcb_io_opt_t, lcb_sockdata_t *, lcb_io_writebuf_t *)
Deprecated:
See lcb_ioC_write2_fn().

Wrapped if not implemented

◆ lcb_ioC_write_callback

typedef void(* lcb_ioC_write_callback) (lcb_sockdata_t *, lcb_io_writebuf_t *, int)
Deprecated:
See lcb_ioC_write2_fn().

This will be wrapped if not implemented

◆ lcb_ioC_write_fn

typedef int(* lcb_ioC_write_fn) (lcb_io_opt_t, lcb_sockdata_t *, lcb_io_writebuf_t *, lcb_ioC_write_callback)

◆ lcb_ioC_write2_callback

typedef void(* lcb_ioC_write2_callback) (lcb_sockdata_t *sd, int status, void *arg)

Callback received when a buffer has been flushed.

Parameters
sdthe socket
statusnonzero on error
argthe opaque handle passed in the write2 call

◆ lcb_ioC_write2_fn

typedef int(* lcb_ioC_write2_fn) (lcb_io_opt_t iops, lcb_sockdata_t *sd, lcb_IOV *iov, lcb_SIZE niov, void *uarg, lcb_ioC_write2_callback callback)

Schedule a flush of a series of buffers to the network.

Parameters
iopsthe I/O context
sdthe socket on which to send
iovan array of IOV structures. The buffers pointed to by the IOVs themselves (i.e. iov->iov_len) must not be freed or modified until the callback has been invoked. The storage for the IOVs themselves (i.e. the array passed in iov) is copied internally to the implementation.
niovthe number of IOV structures within the array
uargan opaque pointer to be passed in the callback
callbackthe callback to invoke. This will be called when the buffers passed have either been completely flushed (and are no longer required) or when an error has taken place.

◆ lcb_ioC_read2_callback

typedef void(* lcb_ioC_read2_callback) (lcb_sockdata_t *sd, lcb_SSIZE nread, void *arg)

Callback invoked when a read has been completed.

Parameters
sdthe socket
nreadnumber of bytes read, or -1 on error
arguser provided argument for callback.

◆ lcb_ioC_read2_fn

typedef int(* lcb_ioC_read2_fn) (lcb_io_opt_t iops, lcb_sockdata_t *sd, lcb_IOV *iov, lcb_SIZE niov, void *uarg, lcb_ioC_read2_callback callback)

Schedule a read from the network.

Parameters
iopsthe I/O context
sdthe socket on which to read
iovan array of IOV structures
niovthe number of IOV structures within the array
uarga pointer passed to the callback
callbackthe callback to invoke
Returns
0 on success, nonzero on error

The IOV array itself shall copied (if needed) into the I/O implementation and thus does not need to be kept in memory after the function has been called. Note that the underlying buffers do need to remain valid until the callback is received.

◆ lcb_ioC_close_fn

typedef unsigned int(* lcb_ioC_close_fn) (lcb_io_opt_t iops, lcb_sockdata_t *sd)

Asynchronously shutdown the socket.

Request an asynchronous close for the specified socket. This merely releases control from the library over to the plugin for the specified socket and does not actually imply that the resources have been closed.

Notable, callbacks for read and write operations will still be invoked in order to maintain proper resource deallocation. However the socket's closed field will be set to true.

Parameters
iopsthe I/O context
sdthe socket structure

◆ lcb_ioC_chkclosed_fn

typedef int(* lcb_ioC_chkclosed_fn) (lcb_io_opt_t iops, lcb_sockdata_t *sd, int flags)

This is the completion variant of lcb_ioE_chkclosed_fn.

See that function for details

Parameters
iops
sd
flags
Returns

◆ lcb_ioC_cntl_fn

typedef int(* lcb_ioC_cntl_fn) (lcb_io_opt_t iops, lcb_sockdata_t *sd, int mode, int option, void *arg)
See also
lcb_ioE_cntl_fn.
Parameters
iops
sd
mode
option
arg
Returns

◆ lcb_io_start_fn

typedef void(* lcb_io_start_fn) (lcb_io_opt_t iops)

Start the event loop.

Parameters
iopsThe I/O context

This should start polling for socket events on all registered watchers and scheduled events. This function should return either when there are no more timers or events pending, or when lcb_io_stop_fn() has been invoked.

◆ lcb_io_tick_fn

typedef void(* lcb_io_tick_fn) (lcb_io_opt_t iops)

Run a single iteration of the event loop without blocking.

This is intended to be an optimization to allow scheduled I/O operations to complete without blocking the main thread

◆ lcb_io_stop_fn

typedef void(* lcb_io_stop_fn) (lcb_io_opt_t iops)

Pause the event loop.

Parameters
iopsThe I/O Context

This function shall suspend the event loop, causing a current invocation to lcb_io_start_fn() to return as soon as possible

◆ lcb_io_procs_fn

typedef void(* lcb_io_procs_fn) (int version, lcb_loop_procs *loop_procs, lcb_timer_procs *timer_procs, lcb_bsd_procs *bsd_procs, lcb_ev_procs *ev_procs, lcb_completion_procs *completion_procs, lcb_iomodel_t *iomodel)
Parameters
versionthe ABI/API version for the proc structures. Note that ABI is forward compatible for all proc structures, meaning that newer versions will always extend new fields and never replace existing ones. However in order to avoid a situation where a newer version of a plugin is loaded against an older version of the library (in which case the plugin will assume the proc table size is actually bigger than it is) the version serves as an indicator for this. The version actually passed is defined in LCB_IOPROCS_VERSION
loop_procsa table to be set to basic loop control routines
timer_procsa table to be set to the timer routines
bsd_procsa table to be set to BSD socket API routines
ev_procsa table to be set to event watcher routines
completion_procsa table to be set to completion routines
iomodelthe I/O model to be used. If this is LCB_IOMODEL_COMPLETION then the contents of bsd_procs will be ignored and completion_procs must be populated. If the mode is LCB_IOMODEL_EVENT then the bsd_procs must be populated and completion_procs is ignored.

Important to note that internally the ev, bsd, and completion field are defined as a union, thus

union {
struct {
} event;
struct lcb_completion_procs completion;
}

thus setting both fields will actually clobber.

Attention
Note that the library takes ownership of the passed tables and it should not be controlled or accessed by the plugin.
This function may not have any side effects as it may be called multiple times.

As opposed to the v0 and v1 IOPS structures that require a table to be populated and returned, the v2 IOPS works differently. Specifically, the IOPS population happens at multiple stages:

  1. The base structure is returned, i.e. lcb_create_NAME_iops where NAME is the name of the plugin
  2. Once the structure is returned, LCB shall invoke the v.v2.get_procs() function. The callback is responsible for populating the relevant fields.

Note that the old v0 and v1 fields are now proxied via this mechanism. It is possible to still monkey-patch the IO routines, but ensure the monkey patching takes place before the instance is created (as the instance will initialize its own IO Table); thus, e.g.

static void monkey_proc_fn(...) {
//
}
static void monkey_patch_io(lcb_io_opt_t io) {
io->v.v0.get_procs = monkey_proc_fn;
}
int main(void) {
lcb_create_st options;
lcb_t instance;
lcb_io_opt_t io;
lcb_create_iops(&io, NULL);
monkey_patch_io(io);
options.v.v0.io = io;
lcb_create(&instance, &options);
// ...
}

Typically the get_procs function will only be called once, and this will happen from within lcb_create(). Thus in order to monkey patch you must ensure that initially the get_procs function itself is first supplanted and then return your customized I/O routines from your own get_procs (in this example, monkey_proc_fn())

◆ lcb_io_create_fn

typedef lcb_error_t(* lcb_io_create_fn) (int version, lcb_io_opt_t *io, void *cookie)

Signature for a loadable plugin's IOPS initializer.

Parameters
versionthe plugin init API version. This will be 0 for this function
ioa pointer to be set to the I/O table
cookiea user-defined argument passed to the I/O initializer
Returns
LCB_SUCCESS on success, an error on failure

Enumeration Type Documentation

◆ lcb_iomodel_t

Enumeration defining the I/O model.

Enumerator
LCB_IOMODEL_EVENT 

Event/Poll style.

LCB_IOMODEL_COMPLETION 

IOCP/Completion style.

◆ lcb_io_ops_type_t

Built-in I/O plugins.

Stability
Committed:
Enumerator
LCB_IO_OPS_INVALID 
Stability
Internal:
LCB_IO_OPS_DEFAULT 
Stability
Internal:
LCB_IO_OPS_LIBEVENT 

Integrate with the libevent loop.

See lcb_create_libevent_io_opts()

LCB_IO_OPS_WINSOCK 
Stability
Internal: