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.

Topics
	libevent
	libev
	libuv

Timer Callbacks
typedef void *(*	lcb_io_timer_create_fn) (lcb_io_opt_t iops)
	Create a new timer object.
typedef void(*	lcb_io_timer_destroy_fn) (lcb_io_opt_t iops, void *timer)
	Destroy a timer handler.
typedef void(*	lcb_io_timer_cancel_fn) (lcb_io_opt_t iops, void *timer)
	Cancel a pending timer callback.
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.

Event Handle Callbacks
typedef void *(*	lcb_ioE_event_create_fn) (lcb_io_opt_t iops)
	Create a new event handle.
typedef void(*	lcb_ioE_event_destroy_fn) (lcb_io_opt_t iops, void *event)
	Destroy an event handle.
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.
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.
#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.
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.
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.
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.
typedef lcb_socket_t(*	lcb_ioE_socket_fn) (lcb_io_opt_t iops, int domain, int type, int protocol)
	Create a new socket.
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.
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.
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.
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.
#define	LCB_IO_SOCKCHECK_PEND_IS_ERROR
	While checking the socket, treat pending data as an error.
#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.
typedef void(*	lcb_io_connect_cb) (lcb_sockdata_t *socket, int status)
	Callback to be invoked upon a connection result.
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.
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.
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.
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.
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.
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.
typedef void(*	lcb_ioC_read2_callback) (lcb_sockdata_t *sd, lcb_SSIZE nread, void *arg)
	Callback invoked when a read has been completed.
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.
typedef unsigned int(*	lcb_ioC_close_fn) (lcb_io_opt_t iops, lcb_sockdata_t *sd)
	Asynchronously shutdown the socket.
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.
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_STATUS 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]	op	The newly created io ops structure
	options	How to create the io ops structure

Returns

LCB_SUCCESS on success

Stability

Uncommitted

Examples

example/libeventdirect/main.c.

lcb_destroy_io_ops()

lcb_STATUS lcb_destroy_io_ops

(

lcb_io_opt_t

op

)

Destroy the plugin handle created by lcb_create_io_ops()

Parameters

op	ops 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	local
struct lcb_nameinfo_st.remote	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

Deprecated

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

Stability

Uncommitted

Examples

example/libeventdirect/main.c.

Data Fields
int	version
union lcb_create_io_ops_st.v	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

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.

lcb_io_timer_create_fn

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.

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

iops	the io structure
timer	the 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

iops	the I/O structure
timer	the 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

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

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

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.

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

iops	the I/O structure
event	the 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

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.

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

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.

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

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

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

	iops	The iops
	sock	The socket
	mode	The mode, can be LCB_IO_CNTL_GET or LCB_IO_CNTL_SET
	option	The option to access
[in,out]	arg	the 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

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.

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

socket	the socket which is being connected
status	the 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

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.

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

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

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

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

iops	the I/O context
sock	the socket from which to retrieve information
ni	a 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)

Deprecated

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)

Deprecated

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

sd	the socket
status	nonzero on error
arg	the 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

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.

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

sd	the socket
nread	number of bytes read, or -1 on error
arg	user 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

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.

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

iops	the I/O context
sd	the 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

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.

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

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

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

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:

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_INSTANCE 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_STATUS(* 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

lcb_iomodel_t

enum 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

enum 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