Detailed Description

I/O Integration comes in two flavors:

Event/Poll Based Integration

Mnemonic: E

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.

Completion/Operation/Buffer Based Integration

Mnemonic: C

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.

Macros
#define	LCB_IOV_LAYOUT_UIO
	Defined if the lcb_IOV structure conforms to `struct iovec`

#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...

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_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 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...

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...

#define	LCB_IO_SOCKCHECK_PEND_IS_ERROR
	While checking the socket, treat pending data as an erorr. More...

#define	LCB_IO_SOCKCHECK_STATUS_CLOSED

#define	LCB_IO_SOCKCHECK_STATUS_OK

#define	LCB_IO_SOCKCHECK_STATUS_UNKNOWN

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...

#define	lcb_io_read_cb

#define	lcb_io_write_cb

Data Structure Documentation

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

struct lcb_nameinfo_st

structure describing a connected socket's endpoints

Data Fields
struct lcb_nameinfo_st	local
struct lcb_nameinfo_st	remote

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]

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

struct lcb_io_writebuf_t

Deprecated:

Data Fields
struct lcb_io_opt_st *	parent
struct lcb_buf_info	buffer

struct lcb_iops_evented_st

IOPS For poll-style notification.

Data Fields
LCB_IOPS_BASE_FIELDS lcb_ioE_socket_fn	socket	Create a socket.
lcb_ioE_connect_fn	connect	Connect a socket.
lcb_ioE_recv_fn	recv	Receive data into a single buffer.
lcb_ioE_send_fn	send	Send data from a single buffer.
lcb_ioE_recvv_fn	recvv	Receive data into multiple buffers.
lcb_ioE_sendv_fn	sendv	Send data from multiple buffers.
lcb_ioE_close_fn	close	Close a socket.
lcb_io_timer_create_fn	create_timer	Create a new timer handle.
lcb_io_timer_destroy_fn	destroy_timer	Destroy a timer handle.
lcb_io_timer_cancel_fn	delete_timer	Cancel a pending timer.
lcb_io_timer_schedule_fn	update_timer	Schedule a timer.
lcb_ioE_event_create_fn	create_event	Create a socket event handle.
lcb_ioE_event_destroy_fn	destroy_event	Destroy a socket event handle.
lcb_ioE_event_watch_fn	update_event	Watch a socket for events.
lcb_ioE_event_cancel_fn	delete_event
lcb_io_stop_fn	stop_event_loop	Start the event loop.
lcb_io_start_fn	run_event_loop	Stop the event loop.

struct lcb_iops_completion_st

IOPS optimized for IOCP-style IO.

The non-IO routines are intended to be binary compatible with the older v0 structure, so I don't have to change too much code initially. Hence the 'pad'. The intent is that the following functions remain ABI-compatible with their v0 counterparts:

create_timer
destroy_timer
update_timer
cookie
error
need_cleanup
run_event_loop
stop_event_loop
The send/recv functions have been replaced with completion- oriented counterparts of start_write and start_read;
connect has been replace by start_connect
update_event, delete_event, and destroy_event are not available in v1.
close is asynchronous, and is implied in destroy_socket. destroy_socket will only be called once all pending operations have been completed.

Note that the 'destructor' itself must be asynchronous, as 'destroy' may be called when there are still pending operations. In this case, it means that libcouchbase is done with the IOPS structure, but the implementation should check that no operations are pending before freeing the data.

Data Fields
LCB_IOPS_BASE_FIELDS lcb_ioC_socket_fn	create_socket

lcb_ioC_connect_fn	start_connect

lcb_ioC_wballoc_fn	create_writebuf

lcb_ioC_wbfree_fn	release_writebuf

lcb_ioC_write_fn	start_write

lcb_ioC_read_fn	start_read

lcb_ioC_close_fn	close_socket

lcb_io_timer_create_fn	create_timer

lcb_io_timer_destroy_fn	destroy_timer

lcb_io_timer_cancel_fn	delete_timer

lcb_io_timer_schedule_fn	update_timer

lcb_ioC_nameinfo_fn	get_nameinfo

void(*	pad1 )(void)

void(*	pad2 )(void)

void(*	send_error )(struct lcb_io_opt_st , lcb_sockdata_t , void()(lcb_sockdata_t ))

lcb_io_stop_fn	stop_event_loop

lcb_io_start_fn	run_event_loop

Field Documentation

void(* send_error)(struct lcb_io_opt_st *, lcb_sockdata_t *, void(*)(lcb_sockdata_t *))

Deprecated:: No longer used

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

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

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

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

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

Macro Definition Documentation

#define LCB_IO_SOCKCHECK_PEND_IS_ERROR

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

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

#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

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

Callback invoked for all poll-like events.

Parameters

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

typedef void*(* lcb_io_timer_create_fn)(lcb_io_opt_t iops)

Create a new timer object.

Parameters

iops	the io structure

Returns: an opaque timer handle. The timer shall remain inactive and shall be destroyed via the lcb_io_timer_destroy_fn routine.

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

iops	the io structure
timer	the opaque handle The timer must have already been cancelled via 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

iops	the I/O structure
timer	the timer to cancel.

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

iops	the I/O structure
timer	a timer previously created with timer_create
usecs	the timer interval
uarg	the user-defined pointer to be passed in the callback
callback	the callback to invoke

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

iops	the 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.

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

iops	the I/O structure
event	the event to free

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

iops	the I/O structure
sock	the socket associated with the event
event	the opaque event object

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

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

iops	the IO context
socket	the socket to watch
event	the event to associate with the socket. If this parameter is
evflags	a 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

uarg	a user defined pointer to be passed to the callback
callback	the 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.

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.

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

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

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

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

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

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)

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

iops	The iops
sock	The socket to check
flags	A 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

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

iops	the IO context
domain	socket address family, e.g. AF_INET
type	the transport type, e.g. SOCK_STREAM
protocol	the IP protocol, e.g. IPPROTO_TCP

Returns: a socket pointer or NULL on failure.

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

socket	the socket which is being connected
status	the status. 0 for success, nonzero on failure

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

iops	the IO context
sd	the socket pointer
dst	the address to connect to
naddr	the size of the address len, e.g. sizeof(struct sockaddr_in)
callback	the callback to invoke when the connection status is determined

Returns: 0 on success, nonzero if a connection could not be scheduled.

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_server	the server listen socket
sd_client	the new client socket
status	if there was an error accepting (in this case, sd_client is NULL

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

iops	the I/O context
server_socket	the socket used to listen with
sockaddr	the local address for listening
callback	the callback to invoke for each new connection

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

iops	the I/O context
sock	the socket from which to retrieve information
ni	a nameinfo structure to populate with the relevant details

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

Deprecated:

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

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

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

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

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

Deprecated:

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

Callback received when a buffer has been flushed.

Parameters

sd	the socket
status	nonzero on error
arg	the opaque handle passed in the write2 call

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

iops	the I/O context
sd	the socket on which to send
iov	an 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.
niov	the number of IOV structures within the array
uarg	an opaque pointer to be passed in the callback
callback	the 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.

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

Callback invoked when a read has been completed.

Parameters

sd	the socket
nread	number of bytes read, or -1 on error
arg	user provided argument for callback.

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

iops	the I/O context
sd	the socket on which to read
iov	an array of IOV structures
niov	the number of IOV structures within the array
uarg	a pointer passed to the callback
callback	the 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.

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

iops	the I/O context
sd	the socket structure

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

typedef void(* lcb_io_start_fn)(lcb_io_opt_t iops)

Start the event loop.

Parameters

iops	The 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.

typedef void(* lcb_io_stop_fn)(lcb_io_opt_t iops)

Pause the event loop.

Parameters

iops	The 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

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

version	the 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_procs	a table to be set to basic loop control routines
timer_procs	a table to be set to the timer routines
bsd_procs	a table to be set to BSD socket API routines
ev_procs	a table to be set to event watcher routines
completion_procs	a table to be set to completion routines
iomodel	the 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 {
        lcb_bsd_procs;
        lcb_ev_procs;
    } 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:

The base structure is returned, i.e. lcb_create_NAME_iops where NAME is the name of the plugin
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())

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

version	the plugin init API version. This will be 0 for this function
io	a pointer to be set to the I/O table
cookie	a user-defined argument passed to the I/O initializer

Returns: LCB_SUCCESS on success, an error on failure

Enumeration Type Documentation

enum lcb_iomodel_t

Enumeration defining the I/O model.

Enumerator
LCB_IOMODEL_EVENT	Event/Poll style.
LCB_IOMODEL_COMPLETION	IOCP/Completion style.

Detailed Description

Event/Poll Based Integration

Completion/Operation/Buffer Based Integration

Macros

Typedefs

Enumerations

Timer Callbacks

Event Handle Callbacks

BSD-API I/O Routines

Completion Routines

Data Structure Documentation

Data Fields

Field Documentation

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation