mt-libcouchbase 1.4.0

data/ext/libcouchbase/include/libcouchbase/iops.h

@@ -0,0 +1,1053 @@
+/* -*- Mode: C; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *     Copyright 2017 Couchbase, Inc.
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permissions and
+ *   limitations under the License.
+ */
+
+#ifndef LIBCOUCHBASE_COUCHBASE_H
+#error "include libcouchbase/couchbase.h first"
+#endif
+
+#ifndef LCB_IOPS_H
+#define LCB_IOPS_H
+
+/**
+ * @file
+ * @brief Public I/O integration interface
+ * @details
+ *
+ * This file provides the public I/O interface for integrating with external
+ * event loops.
+ */
+
+/**
+ * @ingroup lcbio lcb-public-api
+ * @defgroup lcb-io-plugin-api Network I/O
+ * @details
+ *
+ * I/O Integration comes in two flavors:
+ *
+ * @par (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.
+ *
+ *
+ * @par (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.
+ *
+ *
+ * @addtogroup lcb-io-plugin-api
+ * @{
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** @brief Type representing the native socket type of the operating system */
+#ifdef _WIN32
+typedef SOCKET lcb_socket_t;
+#else
+typedef int lcb_socket_t;
+#endif
+
+struct sockaddr;
+
+#ifndef _WIN32
+/** Defined if the lcb_IOV structure conforms to `struct iovec` */
+#define LCB_IOV_LAYOUT_UIO
+typedef struct lcb_iovec_st {
+    void *iov_base;
+    size_t iov_len;
+} lcb_IOV;
+#else
+/** Defined if the lcb_IOV structure conforms to `WSABUF` */
+#define LCB_IOV_LAYOUT_WSABUF
+typedef struct lcb_iovec_st {
+    ULONG iov_len;
+    void *iov_base;
+} lcb_IOV;
+#endif
+
+#if defined(LIBCOUCHBASE_INTERNAL) && !defined(LCB_IOPS_V12_NO_DEPRECATE)
+#define LCB__IOPS_CONCAT2(X, Y) X ## Y
+#define LCB__IOPS_CONCAT(X, Y) LCB__IOPS_CONCAT2(X, Y)
+#define LCB_IOPS_DEPRECATED(X) void (*LCB__IOPS_CONCAT(lcb__iops__dummy, __LINE__))(void)
+#else
+#define LCB_IOPS_DEPRECATED(X) X
+#endif
+
+/** @brief structure describing a connected socket's endpoints */
+struct lcb_nameinfo_st {
+    struct {
+        struct sockaddr *name;
+        int *len;
+    } local;
+
+    struct {
+        struct sockaddr *name;
+        int *len;
+    } remote;
+};
+
+/**
+ * @struct lcb_IOV
+ * @brief structure indicating a buffer and its size
+ *
+ * @details
+ * 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.
+ */
+
+typedef struct lcb_io_opt_st* lcb_io_opt_t;
+
+/**
+ * @brief Callback invoked for all poll-like events
+ *
+ * @param sock the socket associated with the event
+ * @param events the events which activated this callback. This is set of bits
+ *        comprising of LCB_READ_EVENT, LCB_WRITE_EVENT, and LCB_ERROR_EVENT
+ * @param uarg a user-defined pointer passed to the
+ *        lcb_ioE_event_watch_fn routine.
+ */
+typedef void (*lcb_ioE_callback)
+        (lcb_socket_t sock, short events, void *uarg);
+
+/**@name Timer Callbacks
+ *@{*/
+
+/**
+ * @brief Create a new timer object.
+ *
+ * @param iops the io structure
+ * @return 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_create_fn)
+        (lcb_io_opt_t iops);
+
+/**
+ * @brief Destroy a timer handler
+ *
+ * Destroy a timer previously created with lcb_io_timer_create_fn
+ * @param iops the io structure
+ * @param timer the opaque handle
+ * The timer must have already been cancelled via lcb_io_timer_cancel_fn
+ */
+typedef void (*lcb_io_timer_destroy_fn)
+        (lcb_io_opt_t iops, void *timer);
+
+/**
+ * @brief 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.
+ *
+ * @param iops the I/O structure
+ * @param timer the timer to cancel.
+ */
+typedef void (*lcb_io_timer_cancel_fn)
+        (lcb_io_opt_t iops, void *timer);
+
+/**
+ * @brief Schedule a callback to be invoked within a given interval.
+ *
+ * Schedule a timer to be fired within usec microseconds from now
+ * @param iops the I/O structure
+ * @param timer a timer previously created with timer_create
+ * @param usecs the timer interval
+ * @param uarg the user-defined pointer to be passed in the callback
+ * @param callback the callback to invoke
+ */
+typedef int (*lcb_io_timer_schedule_fn)
+        (lcb_io_opt_t iops, void *timer,
+                lcb_U32 usecs,
+                void *uarg,
+                lcb_ioE_callback callback);
+
+/**@}*/
+
+
+/**@name Event Handle Callbacks
+ * @{*/
+
+/**
+ * @brief Create a new event handle.
+ *
+ * An event object may be used to monitor a socket for given I/O readiness events
+ * @param iops the I/O structure.
+ * @return 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_create_fn)
+        (lcb_io_opt_t iops);
+
+/**
+ * @brief Destroy an event handle
+ *
+ * Destroy an event object. The object must not be active.
+ * @param iops the I/O structure
+ * @param event the event to free
+ */
+typedef void (*lcb_ioE_event_destroy_fn)
+        (lcb_io_opt_t iops, void *event);
+
+/**
+ * @deprecated lcb_ioE_event_watch_fn() should be used with `0` for events
+ * @brief Cancel pending callbacks and unwatch a handle.
+ *
+ * @param iops the I/O structure
+ * @param sock the socket associated with the event
+ * @param event the opaque event object
+ *
+ * This function may be called multiple times and shall not fail even if the
+ * event is already inactive.
+ */
+typedef void (*lcb_ioE_event_cancel_fn)
+        (lcb_io_opt_t iops, lcb_socket_t sock, void *event);
+
+
+/** Data is available for reading */
+#define LCB_READ_EVENT 0x02
+/** Data can be written */
+#define LCB_WRITE_EVENT 0x04
+/** Exceptional condition ocurred on socket */
+#define LCB_ERROR_EVENT 0x08
+#define LCB_RW_EVENT (LCB_READ_EVENT|LCB_WRITE_EVENT)
+
+/**
+ * Associate an event with a socket, requesting notification when one of
+ * the events specified in 'flags' becomes available on the socket.
+ *
+ * @param iops the IO context
+ * @param socket the socket to watch
+ * @param event the event to associate with the socket. If this parameter is
+ * @param 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.
+ *
+ * @param uarg a user defined pointer to be passed to the callback
+ * @param 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 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);
+
+/**@}*/
+
+/**@name BSD-API I/O Routines
+ * @{*/
+
+/**
+ * @brief Receive data into a single buffer
+ * @see `recv(2)` socket API call.
+ */
+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);
+
+/** @brief Send data from a single buffer.
+ * @see `send(2)` on POSIX
+ */
+typedef lcb_SSIZE (*lcb_ioE_send_fn)
+        (lcb_io_opt_t iops, lcb_socket_t sock, const void *srcbuf,
+                lcb_SIZE buflen, int _ignored);
+
+/**@brief Read data into a series of buffers.
+ * @see the `recvmsg(2)` function on POSIX */
+typedef lcb_SSIZE (*lcb_ioE_recvv_fn)
+        (lcb_io_opt_t iops, lcb_socket_t sock, lcb_IOV *iov, lcb_SIZE niov);
+
+/**@brief Write data from multiple buffers.
+ * @see the `sendmsg(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);
+
+/**@brief Create a new socket.
+ * @see `socket(2)` on POSIX */
+typedef lcb_socket_t (*lcb_ioE_socket_fn)
+        (lcb_io_opt_t iops, int domain, int type, int protocol);
+
+/**@brief Connect a created socket
+ * @see `connect(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);
+
+/** @internal */
+typedef int (*lcb_ioE_bind_fn)
+        (lcb_io_opt_t iops,
+                lcb_socket_t sock,
+                const struct sockaddr *srcaddr,
+                unsigned int addrlen);
+
+/** @internal */
+typedef int (*lcb_ioE_listen_fn)
+        (lcb_io_opt_t iops,
+                lcb_socket_t bound_sock,
+                unsigned int queuelen);
+
+/** @internal */
+typedef lcb_socket_t (*lcb_ioE_accept_fn)
+        (lcb_io_opt_t iops,
+                lcb_socket_t lsnsock);
+
+/** @brief Close a socket
+ * @see `close(2)` and `shutdown(2)` */
+typedef void (*lcb_ioE_close_fn)
+        (lcb_io_opt_t iops, lcb_socket_t sock);
+
+
+/**
+ * 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
+ */
+#define LCB_IO_SOCKCHECK_PEND_IS_ERROR 1
+
+#define LCB_IO_SOCKCHECK_STATUS_CLOSED 1
+#define LCB_IO_SOCKCHECK_STATUS_OK 0
+#define LCB_IO_SOCKCHECK_STATUS_UNKNOWN -1
+
+/**@brief Check if a socket has been closed or not. This is used to check
+ * a socket's state after a period of inactivity.
+ *
+ *
+ * @param iops The iops
+ * @param sock The socket to check
+ * @param flags A bit set of options.
+ * @return 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 int (*lcb_ioE_chkclosed_fn)
+        (lcb_io_opt_t iops, lcb_socket_t sock, int flags);
+
+
+/** For use with `io{E,C}_cntl_fn`, indicates the setting should be retrieved */
+#define LCB_IO_CNTL_GET 0
+/** For use with lcb_io{E,C}_cntl_fn`, indicates the setting should be modified */
+#define LCB_IO_CNTL_SET 1
+
+/** Disable Nagle's algorithm (use an int) */
+#define LCB_IO_CNTL_TCP_NODELAY 1
+
+/** Enable/Disable TCP Keepalive */
+#define LCB_IO_CNTL_TCP_KEEPALIVE 2
+
+/**
+ * @brief Execute a specificied operation on a socket.
+ * @param iops The iops
+ * @param sock The socket
+ * @param mode The mode, can be @ref LCB_IO_CNTL_GET or @ref LCB_IO_CNTL_SET
+ * @param option The option to access
+ * @param[in,out] arg the argument for the option
+ * @return zero on success, nonzero on failure.
+ */
+typedef int (*lcb_ioE_cntl_fn)
+        (lcb_io_opt_t iops, lcb_socket_t sock, int mode, int option, void *arg);
+/**@}*/
+
+
+struct ringbuffer_st;
+struct lcb_connection_st;
+struct lcbio_SOCKET;
+
+/** @deprecated Ringbuffers are no longer used this way by the library for I/O */
+struct lcb_buf_info {
+    char *root;
+    lcb_SIZE size;
+    struct ringbuffer_st *ringbuffer;
+    struct lcb_iovec_st iov[2];
+};
+
+/**
+ * @brief Socket handle for completion-based I/O
+ *
+ * The sockdata structure is analoguous to an `lcb_socket_t` returned by
+ * the E-model I/O.
+ */
+typedef struct lcb_sockdata_st {
+    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_sockdata_t;
+
+/** @deprecated */
+typedef struct lcb_io_writebuf_st {
+    struct lcb_io_opt_st *parent;
+    struct lcb_buf_info buffer;
+} lcb_io_writebuf_t;
+
+/**@name Completion Routines
+ * @{*/
+
+/**
+ * @brief Create a completion socket handle
+ *
+ * Create an opaque socket handle
+ * @param iops the IO context
+ * @param domain socket address family, e.g. AF_INET
+ * @param type the transport type, e.g. SOCK_STREAM
+ * @param protocol the IP protocol, e.g. IPPROTO_TCP
+ * @return a socket pointer or NULL on failure.
+ */
+typedef lcb_sockdata_t* (*lcb_ioC_socket_fn)
+        (lcb_io_opt_t iops, int domain, int type, int protocol);
+
+/**
+ * @brief Callback to be invoked upon a connection result.
+ * Callback invoked for a connection result.
+ * @param socket the socket which is being connected
+ * @param status the status. 0 for success, nonzero on failure
+ */
+typedef void (*lcb_io_connect_cb)(lcb_sockdata_t *socket, int status);
+
+/**
+ * @brief Request a connection for a socket
+ * @param iops the IO context
+ * @param sd the socket pointer
+ * @param dst the address to connect to
+ * @param naddr the size of the address len, e.g. sizeof(struct sockaddr_in)
+ * @param callback the callback to invoke when the connection status is determined
+ * @return 0 on success, nonzero if a connection could not be scheduled.
+ */
+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);
+
+/**
+ * @brief Callback invoked when a new client connection has been established
+ * @param sd_server the server listen socket
+ * @param sd_client the new client socket
+ * @param status if there was an error accepting (in this case, sd_client is NULL
+ */
+typedef void (lcb_ioC_serve_callback)
+        (lcb_sockdata_t *sd_server,
+                lcb_sockdata_t *sd_client,
+                int status);
+
+/**
+ * Specify that the socket start accepting connections. This should be called
+ * on a newly created non-connected socket
+ * @param iops the I/O context
+ * @param server_socket the socket used to listen with
+ * @param sockaddr the local address for listening
+ * @param callback the callback to invoke for each new connection
+ */
+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);
+
+/**
+ * @brief Request address information on a connected socket
+ * @param iops the I/O context
+ * @param sock the socket from which to retrieve information
+ * @param ni a nameinfo structure to populate with the relevant details
+ */
+typedef int (*lcb_ioC_nameinfo_fn)
+        (lcb_io_opt_t iops,
+                lcb_sockdata_t *sock,
+                struct lcb_nameinfo_st *ni);
+
+/**@deprecated*/
+typedef void (*lcb_ioC_read_callback)(lcb_sockdata_t *sd, lcb_SSIZE nread);
+#define lcb_io_read_cb lcb_ioC_read_callback
+/**@deprecated See lcb_ioC_read2_fn(). Wrapped if not implemented*/
+typedef int (*lcb_ioC_read_fn)(lcb_io_opt_t,lcb_sockdata_t*,lcb_ioC_read_callback);
+/**@deprecated See lcb_ioC_write2_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(). This will be wrapped if not implemented */
+typedef void (*lcb_ioC_write_callback)(lcb_sockdata_t*,lcb_io_writebuf_t*,int);
+#define lcb_io_write_cb lcb_ioC_write_callback
+
+/**@deprecated*/
+typedef int (*lcb_ioC_write_fn)
+        (lcb_io_opt_t,lcb_sockdata_t*,lcb_io_writebuf_t*,lcb_ioC_write_callback);
+
+
+/**
+ * @brief Callback received when a buffer has been flushed
+ * @param sd the socket
+ * @param status nonzero on error
+ * @param arg the opaque handle passed in the write2 call
+ */
+typedef void (*lcb_ioC_write2_callback)
+        (lcb_sockdata_t *sd,
+                int status,
+                void *arg);
+
+/**
+ * @brief Schedule a flush of a series of buffers to the network
+ *
+ * @param iops the I/O context
+ * @param sd the socket on which to send
+ * @param 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.
+ *
+ * @param niov the number of IOV structures within the array
+ * @param uarg an opaque pointer to be passed in the callback
+ * @param 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 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);
+
+
+/**
+ * @brief Callback invoked when a read has been completed
+ * @param sd the socket
+ * @param nread number of bytes read, or -1 on error
+ * @param arg user provided argument for callback.
+ */
+typedef void (*lcb_ioC_read2_callback)
+        (lcb_sockdata_t *sd, lcb_SSIZE nread, void *arg);
+/**
+ * @brief Schedule a read from the network
+ * @param iops the I/O context
+ * @param sd the socket on which to read
+ * @param iov an array of IOV structures
+ * @param niov the number of IOV structures within the array
+ * @param uarg a pointer passed to the callback
+ * @param callback the callback to invoke
+ * @return 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 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);
+
+/**
+ * @brief 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.
+ *
+ * @param iops the I/O context
+ * @param sd the socket structure
+ */
+typedef unsigned int (*lcb_ioC_close_fn)
+        (lcb_io_opt_t iops,
+                lcb_sockdata_t *sd);
+
+/**
+ * This is the completion variant of @ref lcb_ioE_chkclosed_fn. See that
+ * function for details
+ *
+ * @param iops
+ * @param sd
+ * @param flags
+ * @return
+ */
+typedef int (*lcb_ioC_chkclosed_fn)
+        (lcb_io_opt_t iops, lcb_sockdata_t *sd, int flags);
+
+/**
+ * @see lcb_ioE_cntl_fn.
+ *
+ * @param iops
+ * @param sd
+ * @param mode
+ * @param option
+ * @param arg
+ * @return
+ */
+typedef int (*lcb_ioC_cntl_fn)
+        (lcb_io_opt_t iops, lcb_sockdata_t *sd, int mode, int option, void *arg);
+
+/**@}*/
+
+/**
+ * @brief Start the event loop
+ * @param 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_start_fn)(lcb_io_opt_t iops);
+
+/**
+ * @brief 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
+ */
+typedef void (*lcb_io_tick_fn)(lcb_io_opt_t iops);
+
+/**
+ * @brief Pause the event loop
+ * @param 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_stop_fn)(lcb_io_opt_t iops);
+
+LCB_DEPRECATED(typedef void (*lcb_io_error_cb)(lcb_sockdata_t *socket));
+
+#define LCB_IOPS_BASE_FIELDS \
+    void *cookie; \
+    int error; \
+    int need_cleanup;
+
+struct lcb_iops_evented_st {
+    LCB_IOPS_BASE_FIELDS
+    LCB_IOPS_DEPRECATED(lcb_ioE_socket_fn socket);
+    LCB_IOPS_DEPRECATED(lcb_ioE_connect_fn connect);
+    LCB_IOPS_DEPRECATED(lcb_ioE_recv_fn recv);
+    LCB_IOPS_DEPRECATED(lcb_ioE_send_fn send);
+    LCB_IOPS_DEPRECATED(lcb_ioE_recvv_fn recvv);
+    LCB_IOPS_DEPRECATED(lcb_ioE_sendv_fn sendv);
+    LCB_IOPS_DEPRECATED(lcb_ioE_close_fn close);
+    LCB_IOPS_DEPRECATED(lcb_io_timer_create_fn create_timer);
+    LCB_IOPS_DEPRECATED(lcb_io_timer_destroy_fn destroy_timer);
+    LCB_IOPS_DEPRECATED(lcb_io_timer_cancel_fn delete_timer);
+    LCB_IOPS_DEPRECATED(lcb_io_timer_schedule_fn update_timer);
+    LCB_IOPS_DEPRECATED(lcb_ioE_event_create_fn create_event);
+    LCB_IOPS_DEPRECATED(lcb_ioE_event_destroy_fn destroy_event);
+    LCB_IOPS_DEPRECATED(lcb_ioE_event_watch_fn update_event);
+    LCB_IOPS_DEPRECATED(lcb_ioE_event_cancel_fn delete_event);
+    LCB_IOPS_DEPRECATED(lcb_io_stop_fn stop_event_loop);
+    LCB_IOPS_DEPRECATED(lcb_io_start_fn run_event_loop);
+};
+
+struct lcb_iops_completion_st {
+    LCB_IOPS_BASE_FIELDS
+    LCB_IOPS_DEPRECATED(lcb_ioC_socket_fn create_socket);
+    LCB_IOPS_DEPRECATED(lcb_ioC_connect_fn start_connect);
+    LCB_IOPS_DEPRECATED(lcb_ioC_wballoc_fn create_writebuf);
+    LCB_IOPS_DEPRECATED(lcb_ioC_wbfree_fn release_writebuf);
+    LCB_IOPS_DEPRECATED(lcb_ioC_write_fn start_write);
+    LCB_IOPS_DEPRECATED(lcb_ioC_read_fn start_read);
+    LCB_IOPS_DEPRECATED(lcb_ioC_close_fn close_socket);
+    LCB_IOPS_DEPRECATED(lcb_io_timer_create_fn create_timer);
+    LCB_IOPS_DEPRECATED(lcb_io_timer_destroy_fn destroy_timer);
+    LCB_IOPS_DEPRECATED(lcb_io_timer_cancel_fn delete_timer);
+    LCB_IOPS_DEPRECATED(lcb_io_timer_schedule_fn update_timer);
+    LCB_IOPS_DEPRECATED(lcb_ioC_nameinfo_fn get_nameinfo);
+    void (*pad1)(void);
+    void (*pad2)(void);
+    LCB_IOPS_DEPRECATED(void (*send_error)(struct lcb_io_opt_st*, lcb_sockdata_t*,void(*)(lcb_sockdata_t*)));
+    LCB_IOPS_DEPRECATED(lcb_io_stop_fn stop_event_loop);
+    LCB_IOPS_DEPRECATED(lcb_io_start_fn run_event_loop);
+};
+
+/** @brief Common functions for starting and stopping timers */
+typedef struct lcb_timerprocs_st {
+    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_timer_procs;
+
+/** @brief Common functions for starting and stopping the event loop */
+typedef struct lcb_loopprocs_st {
+    lcb_io_start_fn start;
+    lcb_io_stop_fn stop;
+    lcb_io_tick_fn tick;
+} lcb_loop_procs;
+
+/** @brief Functions wrapping the Berkeley Socket API */
+typedef struct lcb_bsdprocs_st {
+    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_bsd_procs;
+
+/** @brief Functions handling socket watcher events */
+typedef struct lcb_evprocs_st {
+    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_ev_procs;
+
+/** @brief Functions for completion-based I/O */
+typedef struct {
+    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_completion_procs;
+
+/**
+ * Enumeration defining the I/O model
+ */
+typedef enum {
+    LCB_IOMODEL_EVENT, /**< Event/Poll style */
+    LCB_IOMODEL_COMPLETION /**< IOCP/Completion style */
+} lcb_iomodel_t;
+
+/**
+ * @param 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`
+ *
+ * @param loop_procs a table to be set to basic loop control routines
+ * @param timer_procs a table to be set to the timer routines
+ * @param bsd_procs a table to be set to BSD socket API routines
+ * @param ev_procs a table to be set to event watcher routines
+ * @param completion_procs a table to be set to completion routines
+ * @param 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
+ * @code{.c}
+ * union {
+ *     struct {
+ *         lcb_bsd_procs;
+ *         lcb_ev_procs;
+ *     } event;
+ *     struct lcb_completion_procs completion;
+ * }
+ * @endcode
+ * 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.
+ *
+ * @attention
+ * 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.
+ * @code{.c}
+ * 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);
+ *     // ...
+ * }
+ * @endcode
+ *
+ * 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 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);
+
+struct lcbio_TABLE;
+struct lcb_iops2_st {
+    LCB_IOPS_BASE_FIELDS
+    lcb_io_procs_fn get_procs;
+    struct lcbio_TABLE *iot;
+};
+
+/* This is here to provide backwards compatibility with older (broken) clients
+ * which attempt to 'subclass' the select plugin, or similar. In this case we
+ * provide 17 callback fields (unused here) which the plugin implementation
+ * may set, so that the older code can continue to function without upgrading
+ * the client to a newer version. This should not be used except by internal
+ * plugins; specifically the ABI layout of this field is subject to change
+ * (for example, additional fields may be added or existing fields may be
+ * renamed/removed) without notice.
+ */
+typedef void (*lcb__iops3fndummy)(void);
+struct lcb_iops3_st {
+    LCB_IOPS_BASE_FIELDS
+    lcb__iops3fndummy pads[17];
+    lcb_io_procs_fn get_procs;
+    struct lcbio_TABLE *iot;
+};
+
+/**
+ * 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)
+ */
+#define LCB_IOPROCS_VERSION 4
+
+#define LCB_IOPS_BASEFLD(iops, fld) ((iops)->v.base).fld
+#define LCB_IOPS_ERRNO(iops) LCB_IOPS_BASEFLD(iops, error)
+
+struct lcb_io_opt_st {
+    int version;
+    void *dlhandle;
+    void (*destructor)(struct lcb_io_opt_st *iops);
+    union {
+        struct {
+            LCB_IOPS_BASE_FIELDS
+        } base;
+
+        /** These two names are deprecated internally */
+        struct lcb_iops_evented_st v0;
+        struct lcb_iops_completion_st v1;
+        struct lcb_iops2_st v2;
+        struct lcb_iops3_st v3;
+    } v;
+};
+
+/**
+ * @brief Signature for a loadable plugin's IOPS initializer
+ *
+ * @param version the plugin init API version. This will be 0 for this function
+ * @param io a pointer to be set to the I/O table
+ * @param cookie a user-defined argument passed to the I/O initializer
+ * @return LCB_SUCCESS on success, an error on failure
+ */
+typedef lcb_error_t (*lcb_io_create_fn)
+        (int version, lcb_io_opt_t *io, void *cookie);
+
+
+/**
+ * @volatile
+ *
+ * This is an alternative to copying the 'bsdio-inl.c' file around. It is
+ * designed specifically for the @ref 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.
+ * @code{.c}
+ * 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);
+ * @endcode
+ *
+ * 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.
+ */
+LIBCOUCHBASE_API
+void
+lcb_iops_wire_bsd_impl2(lcb_bsd_procs *procs, int version);
+
+/******************************************************************************
+ ******************************************************************************
+ ** IO CREATION                                                              **
+ ******************************************************************************
+ ******************************************************************************/
+
+/**
+ * @brief Built-in I/O plugins
+ * @committed
+ */
+typedef enum {
+    LCB_IO_OPS_INVALID = 0x00, /**< @internal */
+    LCB_IO_OPS_DEFAULT = 0x01, /**< @internal */
+
+    /** Integrate with the libevent loop. See lcb_create_libevent_io_opts() */
+    LCB_IO_OPS_LIBEVENT = 0x02,
+    LCB_IO_OPS_WINSOCK = 0x03, /**< @internal */
+    LCB_IO_OPS_LIBEV = 0x04,
+    LCB_IO_OPS_SELECT = 0x05,
+    LCB_IO_OPS_WINIOCP = 0x06,
+    LCB_IO_OPS_LIBUV = 0x07
+} lcb_io_ops_type_t;
+
+/** @brief IO Creation for builtin plugins */
+typedef struct {
+    lcb_io_ops_type_t type; /**< The predefined type you want to create */
+    void *cookie; /**< Plugin-specific argument */
+} lcb_IOCREATEOPTS_BUILTIN;
+
+#ifndef __LCB_DOXYGEN__
+/* These are mostly internal structures which may be in use by older applications.*/
+typedef struct { const char *sofile; const char *symbol; void *cookie; } lcb_IOCREATEOPTS_DSO;
+typedef struct { lcb_io_create_fn create; void *cookie; } lcb_IOCREATEOPS_FUNCTIONPOINTER;
+#endif
+
+/** @uncommitted */
+struct lcb_create_io_ops_st {
+    int version;
+    union {
+        lcb_IOCREATEOPTS_BUILTIN v0;
+        lcb_IOCREATEOPTS_DSO v1;
+        lcb_IOCREATEOPS_FUNCTIONPOINTER v2;
+    } v;
+};
+
+/**
+ * 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.
+ *
+ * @param[out] op The newly created io ops structure
+ * @param options How to create the io ops structure
+ * @return @ref LCB_SUCCESS on success
+ * @uncommitted
+ */
+LIBCOUCHBASE_API
+lcb_error_t lcb_create_io_ops(lcb_io_opt_t *op, const struct lcb_create_io_ops_st *options);
+
+/**
+ * Destroy the plugin handle created by lcb_create_io_ops()
+ * @param op ops structure
+ * @return LCB_SUCCESS on success
+ * @uncommitted
+ */
+LIBCOUCHBASE_API
+lcb_error_t lcb_destroy_io_ops(lcb_io_opt_t op);
+
+#ifdef __cplusplus
+}
+#endif
+
+/**@}*/
+
+#endif