mt-libcouchbase 1.4.0

data/ext/libcouchbase/plugins/io/iocp/iocp_loop.c

@@ -0,0 +1,295 @@
+/* -*- Mode: C; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *     Copyright 2013 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.
+ */
+
+/**
+ * New-Style v2 plugin for Windows, Using IOCP
+ *
+ * This file contains the core routines which actually make up the
+ * various "loops" of the event loop.
+ *
+ * @author Mark Nunberg
+ */
+
+#include "iocp_iops.h"
+#include <stdio.h>
+
+static sGetQueuedCompletionStatusEx pGetQueuedCompletionStatusEx = NULL;
+static int Have_GQCS_Ex = 1;
+
+void iocp_initialize_loop_globals(void)
+{
+    HMODULE hKernel32;
+    static IOCP_SYNCTYPE initialized = 0;
+
+    if (!IOCP_INITONCE(initialized)) {
+        return;
+    }
+
+    hKernel32 = GetModuleHandleA("kernel32.dll");
+    if (!hKernel32) {
+        fprintf(stderr, "Couldn't load Kernel32.dll: [%u]\n", GetLastError());
+        return;
+    }
+
+    pGetQueuedCompletionStatusEx = (sGetQueuedCompletionStatusEx)GetProcAddress(hKernel32, "GetQueuedCompletionStatusEx");
+    if (pGetQueuedCompletionStatusEx == NULL) {
+        Have_GQCS_Ex = 0;
+        fprintf(stderr, "Couldn't load GetQueuedCompletionStatusEx. Using fallback [%u]\n",
+                GetLastError());
+    }
+}
+
+/**
+ * Make these macros prominent.
+ * It's important that they get called after each of our own calls to
+ * lcb.
+ */
+#define LOOP_CAN_CONTINUE(io) ((io)->breakout == FALSE)
+#define DO_IF_BREAKOUT(io, e) if (!LOOP_CAN_CONTINUE(io)) { e; }
+#define HAS_QUEUED_IO(io) (io)->n_iopending
+
+void iocp_write_done(iocp_t *io, iocp_write_t *w, int status)
+{
+    lcb_ioC_write2_callback callback = w->cb;
+    void *uarg = w->uarg;
+    iocp_sockdata_t *sd = w->ol_write.sd;
+
+    if (w->state == IOCP_WRITEBUF_ALLOCATED) {
+        free(w);
+    } else {
+        w->state = IOCP_WRITEBUF_AVAILABLE;
+    }
+    callback(&sd->sd_base, status, uarg);
+}
+
+/**
+ * Handles a single OVERLAPPED entry, and invokes
+ * the appropriate event
+ */
+static void
+handle_single_overlapped(iocp_t *io, OVERLAPPED *lpOverlapped,
+    ULONG_PTR lpCompletionKey, DWORD dwNumberOfBytesTransferred)
+{
+    union { iocp_write_t *w; iocp_connect_t *conn; } u_ol;
+    void *pointer_to_free = NULL;
+    int opstatus = 0;
+    int ws_status;
+    int action;
+    iocp_overlapped_t *ol = (iocp_overlapped_t *)lpOverlapped;
+    iocp_sockdata_t *sd = (iocp_sockdata_t *)lpCompletionKey;
+
+    IOCP_LOG(IOCP_TRACE, "OL=%p, NB=%lu", ol, dwNumberOfBytesTransferred);
+
+    ws_status = iocp_overlapped_status(lpOverlapped);
+
+    if (ws_status) {
+        IOCP_LOG(IOCP_WARN, "Got negative status for %p: %d", ol, ws_status);
+        io->base.v.v2.error = iocp_w32err_2errno(ws_status);
+        opstatus = -1;
+    }
+
+    action = ol->action;
+
+    switch (action) {
+    case LCBIOCP_ACTION_READ:
+        /** Nothing special in the OVERLAPPED. */
+        if (sd->rdcb) {
+            sd->rdcb(&sd->sd_base, dwNumberOfBytesTransferred, sd->rdarg);
+        }
+        break;
+
+    case LCBIOCP_ACTION_WRITE:
+        u_ol.w = IOCP_WRITEOBJ_FROM_OVERLAPPED(lpOverlapped);
+        iocp_write_done(io, u_ol.w, opstatus);
+        break;
+
+    case LCBIOCP_ACTION_CONNECT:
+        u_ol.conn = (iocp_connect_t *)ol;
+
+        if (opstatus == 0) {
+            /* This "Syncs" the connected state on the socket.. */
+            int rv = setsockopt(ol->sd->sSocket,
+                SOL_SOCKET, SO_UPDATE_CONNECT_CONTEXT, NULL, 0);
+
+            if (rv == SOCKET_ERROR) {
+                iocp_set_last_error(&io->base, ol->sd->sSocket);
+                opstatus = -1;
+            }
+        }
+        u_ol.conn->cb(&sd->sd_base, opstatus);
+        pointer_to_free = u_ol.conn;
+        break;
+
+    default:
+        fprintf(stderr, "COUCHBASE-IOCP: Unrecognized OVERLAPPED action %d\n", (int)action);
+        assert(0);
+        return;
+    }
+
+    iocp_on_dequeued(io, sd, action);
+    free(pointer_to_free);
+}
+
+static int dequeue_io_impl_ex(iocp_t *io, DWORD msTimeout)
+{
+    OVERLAPPED_ENTRY entries[64];
+    BOOL status;
+    ULONG ulRemoved;
+    const unsigned max_entries = sizeof(entries) / sizeof(entries[0]);
+    unsigned int ii;
+
+    status = pGetQueuedCompletionStatusEx(io->hCompletionPort,
+        entries, max_entries, &ulRemoved, msTimeout, FALSE);
+
+    if (status == FALSE || ulRemoved == 0) {
+        return 0;
+    }
+
+    for (ii = 0; ii < ulRemoved; ii++) {
+        OVERLAPPED_ENTRY *ent = entries + ii;
+
+        io->n_iopending--;
+        handle_single_overlapped(io, ent->lpOverlapped, ent->lpCompletionKey,
+            ent->dwNumberOfBytesTransferred);
+    }
+
+    return LOOP_CAN_CONTINUE(io);
+}
+
+static int dequeue_io_impl_compat(iocp_t *io, DWORD msTimeout)
+{
+    BOOL result;
+    DWORD dwNbytes;
+    ULONG_PTR ulPtr;
+    OVERLAPPED *lpOverlapped;
+
+    result = GetQueuedCompletionStatus(io->hCompletionPort,
+        &dwNbytes, &ulPtr, &lpOverlapped, msTimeout);
+
+    if (lpOverlapped == NULL) {
+        IOCP_LOG(IOCP_TRACE, "No events left");
+        /** Nothing to do here */
+        return 0;
+    }
+
+    io->n_iopending--;
+    handle_single_overlapped(io, lpOverlapped, ulPtr, dwNbytes);
+    return LOOP_CAN_CONTINUE(io);
+}
+
+static void deque_expired_timers(iocp_t *io, lcb_U64 now)
+{
+    while (LOOP_CAN_CONTINUE(io)) {
+        iocp_timer_t *timer = iocp_tmq_pop(&io->timer_queue.list, now);
+
+        if (!timer) {
+            return;
+        }
+
+        timer->is_active = 0;
+        timer->cb(-1, 0, timer->arg);
+    }
+}
+
+/** Maximum amount of time the I/O can hog the loop */
+#define IOCP_IOLOOP_MAXTIME 1000
+
+static int should_yield(lcb_U32 start)
+{
+    lcb_U32 now = iocp_micros();
+    return now - start > IOCP_IOLOOP_MAXTIME;
+}
+
+/**
+ * I'd like to make several behavioral guidelines here:
+ *
+ * 1) LCB shall call breakout if it wishes to terminate the loop.
+ * 2) We shall not handle the case where the user accidentally calls lcb_wait()
+ *    while not having anything pending. That's just too bad.
+ */
+void iocp_run(lcb_io_opt_t iobase)
+{
+    iocp_t *io = (iocp_t *)iobase;
+    lcb_U64 now = 0;
+    DWORD tmo;
+    int remaining;
+
+    if (!io->breakout) {
+        return;
+    }
+
+    io->breakout = FALSE;
+    IOCP_LOG(IOCP_INFO, "do-loop BEGIN");
+
+    do {
+        /** To ensure we don't starve pending timers, use an iteration */
+        lcb_U32 usStartTime;
+
+        if (!now) {
+            now = iocp_millis();
+        }
+
+        do {
+            tmo = (DWORD)iocp_tmq_next_timeout(&io->timer_queue.list, now);
+            IOCP_LOG(IOCP_TRACE, "Timeout=%lu msec", tmo);
+
+            if (tmo) {
+                break;
+            }
+
+            deque_expired_timers(io, now);
+        } while (tmo == 0 && LOOP_CAN_CONTINUE(io));
+
+        if (!LOOP_CAN_CONTINUE(io)) {
+            break;
+        }
+
+        /** TODO: Use reference counting */
+        if (tmo == INFINITE) {
+            if (HAS_QUEUED_IO(io)) {
+                assert(0 && "Found I/O without any timers");
+            }
+            break;
+        }
+
+        usStartTime = iocp_micros();
+        do {
+            remaining = Have_GQCS_Ex ?
+                dequeue_io_impl_ex(io, tmo) : dequeue_io_impl_compat(io, tmo);
+            tmo = 0;
+        } while (LOOP_CAN_CONTINUE(io) &&
+            remaining && should_yield(usStartTime) == 0);
+
+        IOCP_LOG(IOCP_TRACE, "Stopped IO loop");
+
+        if (LOOP_CAN_CONTINUE(io)) {
+            now = iocp_millis();
+            deque_expired_timers(io, now);
+            tmo = (DWORD)iocp_tmq_next_timeout(&io->timer_queue.list, now);
+        }
+    } while (LOOP_CAN_CONTINUE(io) && (HAS_QUEUED_IO(io) || tmo != INFINITE));
+
+    IOCP_LOG(IOCP_INFO, "do-loop END");
+    io->breakout = TRUE;
+}
+
+void iocp_stop(lcb_io_opt_t iobase)
+{
+    iocp_t *io = (iocp_t *)iobase;
+    IOCP_LOG(IOCP_INFO, "Breakout requested");
+    io->breakout = TRUE;
+}

data/ext/libcouchbase/plugins/io/iocp/iocp_timer.c

@@ -0,0 +1,79 @@
+/* -*- Mode: C; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+*     Copyright 2013 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.
+*/
+
+/**
+* New-Style v1 plugin for Windows, Using IOCP
+* @author Mark Nunberg
+* @author Sergey Avseyev
+*/
+
+#include "iocp_iops.h"
+
+static int iocp_timer_cmp_asc(lcb_list_t *a, lcb_list_t *b)
+{
+    iocp_timer_t *aa, *bb;
+
+    aa = LCB_LIST_ITEM(a, iocp_timer_t, list);
+    bb = LCB_LIST_ITEM(b, iocp_timer_t, list);
+    if (aa->ms > bb->ms) {
+        return 1;
+    } else if (aa->ms < bb->ms) {
+        return -1;
+    } else {
+        return 0;
+    }
+}
+
+lcb_uint64_t iocp_tmq_next_timeout(lcb_list_t *list, lcb_uint64_t now)
+{
+    if (LCB_LIST_IS_EMPTY(list)) {
+        return INFINITE;
+
+    } else {
+        iocp_timer_t *tt;
+        tt = LCB_LIST_ITEM(list->next, iocp_timer_t, list);
+        return tt->ms > now ? tt->ms - now : 0;
+    }
+}
+
+iocp_timer_t *iocp_tmq_pop(lcb_list_t *list, lcb_uint64_t now)
+{
+    iocp_timer_t *tt;
+
+    if (LCB_LIST_IS_EMPTY(list)) {
+        return NULL;
+    }
+    tt = LCB_LIST_ITEM(list->next, iocp_timer_t, list);
+    if (tt->ms > now) {
+        return NULL;
+    }
+    lcb_list_delete(&tt->list);
+    return tt;
+}
+
+void iocp_tmq_add(lcb_list_t *list, iocp_timer_t *timer)
+{
+    IOCP_LOG(IOCP_TRACE, "Adding timer %p with ms %lu", timer, timer->ms);
+    lcb_list_add_sorted(list, &timer->list, iocp_timer_cmp_asc);
+}
+
+void iocp_tmq_del(lcb_list_t *list, iocp_timer_t *timer)
+{
+    lcb_list_delete(&timer->list);
+    IOCP_LOG(IOCP_TRACE, "Removing %p. Empty?=%d", timer, LCB_LIST_IS_EMPTY(list));
+    (void)list;
+}

data/ext/libcouchbase/plugins/io/iocp/iocp_util.c

@@ -0,0 +1,229 @@
+/* -*- Mode: C; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *     Copyright 2013 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.
+ */
+
+/**
+ * New-Style v2 plugin for Windows, Using IOCP.
+ * This file contains various utility functions used by the plugin
+ * @author Mark Nunberg
+ */
+
+#include "iocp_iops.h"
+#include <sys/types.h>
+#include <sys/timeb.h>
+#include <time.h>
+#include "config.h"
+#include <libcouchbase/plugins/io/wsaerr-inl.c>
+
+#if defined(__MINGW32__) && !defined(_ftime_s)
+#define _ftime_s _ftime /** Mingw doens't have the _s variant */
+#endif
+
+int iocp_w32err_2errno(DWORD error)
+{
+    return wsaerr_map_impl(error);
+}
+
+DWORD iocp_set_last_error(lcb_io_opt_t io, SOCKET sock)
+{
+    int werr = GetLastError();
+    io->v.v2.error = iocp_w32err_2errno(werr);
+    return werr;
+}
+
+lcb_uint32_t iocp_micros(void)
+{
+    return (lcb_uint32_t)(gethrtime() / 1000);
+}
+
+LPFN_CONNECTEX iocp_initialize_connectex(SOCKET sock)
+{
+    LPFN_CONNECTEX ret = NULL;
+    DWORD dwBytes;
+    GUID ce_guid = WSAID_CONNECTEX;
+
+    WSAIoctl(sock,
+             SIO_GET_EXTENSION_FUNCTION_POINTER,
+             &ce_guid,
+             sizeof(ce_guid),
+             &ret,
+             sizeof(&ret),
+             &dwBytes,
+             NULL,
+             NULL);
+
+    return ret;
+}
+
+int iocp_just_scheduled(iocp_t *io, iocp_overlapped_t *ol, int status)
+{
+    DWORD err = GetLastError();
+    IOCP_LOG(IOCP_TRACE, "Pending count: %d", io->n_iopending);
+    if ((status != 0 && err == WSA_IO_PENDING) || status == 0) {
+        io->n_iopending++;
+        ol->sd->refcount++;
+        return 0;
+    }
+
+    /**
+     * Otherwise, there's something wrong
+     */
+    IOCP_LOG(IOCP_ERR, "Got non-harmless error for %p: %d", ol, (int)err);
+    io->base.v.v2.error = iocp_w32err_2errno(err);
+    return -1;
+}
+
+void iocp_socket_decref(iocp_t *io, iocp_sockdata_t *sd)
+{
+    if (--sd->refcount) {
+        return;
+    }
+
+    if (sd->sSocket != INVALID_SOCKET) {
+        closesocket(sd->sSocket);
+    }
+
+    lcb_list_delete(&sd->list);
+
+    (void)io;
+    free(sd);
+}
+
+void iocp_on_dequeued(iocp_t *io, iocp_sockdata_t *sd, int action)
+{
+    IOCP_LOG(IOCP_TRACE, "Dequeing. A=%d, Pending=%d", action, io->n_iopending);
+    iocp_socket_decref(io, sd);
+}
+
+/**This following function was copied from libuv.
+ * See http://github.com/joyent/libuv for more details */
+int iocp_overlapped_status(OVERLAPPED *lpOverlapped)
+{
+    NTSTATUS status = (NTSTATUS)lpOverlapped->Internal;
+    switch (status) {
+    case 0:
+        return ERROR_SUCCESS;
+
+    case STATUS_PENDING:
+        return ERROR_IO_PENDING;
+
+    case STATUS_INVALID_HANDLE:
+    case STATUS_OBJECT_TYPE_MISMATCH:
+        return WSAENOTSOCK;
+
+    case STATUS_INSUFFICIENT_RESOURCES:
+    case STATUS_PAGEFILE_QUOTA:
+    case STATUS_COMMITMENT_LIMIT:
+    case STATUS_WORKING_SET_QUOTA:
+    case STATUS_NO_MEMORY:
+    case STATUS_CONFLICTING_ADDRESSES:
+    case STATUS_QUOTA_EXCEEDED:
+    case STATUS_TOO_MANY_PAGING_FILES:
+    case STATUS_REMOTE_RESOURCES:
+    case STATUS_TOO_MANY_ADDRESSES:
+        return WSAENOBUFS;
+
+    case STATUS_SHARING_VIOLATION:
+    case STATUS_ADDRESS_ALREADY_EXISTS:
+        return WSAEADDRINUSE;
+
+    case STATUS_LINK_TIMEOUT:
+    case STATUS_IO_TIMEOUT:
+    case STATUS_TIMEOUT:
+        return WSAETIMEDOUT;
+
+    case STATUS_GRACEFUL_DISCONNECT:
+        return WSAEDISCON;
+
+    case STATUS_REMOTE_DISCONNECT:
+    case STATUS_CONNECTION_RESET:
+    case STATUS_LINK_FAILED:
+    case STATUS_CONNECTION_DISCONNECTED:
+    case STATUS_PORT_UNREACHABLE:
+    case STATUS_HOPLIMIT_EXCEEDED:
+        return WSAECONNRESET;
+
+    case STATUS_LOCAL_DISCONNECT:
+    case STATUS_TRANSACTION_ABORTED:
+    case STATUS_CONNECTION_ABORTED:
+        return WSAECONNABORTED;
+
+    case STATUS_BAD_NETWORK_PATH:
+    case STATUS_NETWORK_UNREACHABLE:
+    case STATUS_PROTOCOL_UNREACHABLE:
+        return WSAENETUNREACH;
+
+    case STATUS_HOST_UNREACHABLE:
+        return WSAEHOSTUNREACH;
+
+    case STATUS_CANCELLED:
+    case STATUS_REQUEST_ABORTED:
+        return WSAEINTR;
+
+    case STATUS_BUFFER_OVERFLOW:
+    case STATUS_INVALID_BUFFER_SIZE:
+        return WSAEMSGSIZE;
+
+    case STATUS_BUFFER_TOO_SMALL:
+    case STATUS_ACCESS_VIOLATION:
+        return WSAEFAULT;
+
+    case STATUS_DEVICE_NOT_READY:
+    case STATUS_REQUEST_NOT_ACCEPTED:
+        return WSAEWOULDBLOCK;
+
+    case STATUS_INVALID_NETWORK_RESPONSE:
+    case STATUS_NETWORK_BUSY:
+    case STATUS_NO_SUCH_DEVICE:
+    case STATUS_NO_SUCH_FILE:
+    case STATUS_OBJECT_PATH_NOT_FOUND:
+    case STATUS_OBJECT_NAME_NOT_FOUND:
+    case STATUS_UNEXPECTED_NETWORK_ERROR:
+        return WSAENETDOWN;
+
+    case STATUS_INVALID_CONNECTION:
+        return WSAENOTCONN;
+
+    case STATUS_REMOTE_NOT_LISTENING:
+    case STATUS_CONNECTION_REFUSED:
+        return WSAECONNREFUSED;
+
+    case STATUS_PIPE_DISCONNECTED:
+        return WSAESHUTDOWN;
+
+    case STATUS_INVALID_ADDRESS:
+    case STATUS_INVALID_ADDRESS_COMPONENT:
+        return WSAEADDRNOTAVAIL;
+
+    case STATUS_NOT_SUPPORTED:
+    case STATUS_NOT_IMPLEMENTED:
+        return WSAEOPNOTSUPP;
+
+    case STATUS_ACCESS_DENIED:
+        return WSAEACCES;
+
+    default:
+        if ((status & (FACILITY_NTWIN32 << 16)) == (FACILITY_NTWIN32 << 16) &&
+                (status & (ERROR_SEVERITY_ERROR | ERROR_SEVERITY_WARNING))) {
+            /* It's a windows error that has been previously mapped to an */
+            /* ntstatus code. */
+            return (DWORD)(status & 0xffff);
+        } else {
+            /* The default fallback for unmappable ntstatus codes. */
+            return WSAEINVAL;
+        }
+    }
+}

data/ext/libcouchbase/plugins/io/libev/CMakeLists.txt

@@ -0,0 +1,31 @@
+IF(LCB_INSTALL_HEADERS)
+  INSTALL(
+      FILES
+      libev_io_opts.h
+      DESTINATION
+      include/libcouchbase)
+ENDIF(LCB_INSTALL_HEADERS)
+
+IF(NOT (HAVE_LIBEV3 OR HAVE_LIBEV4))
+    RETURN()
+ENDIF()
+
+
+ADD_LIBRARY(couchbase_libev SHARED plugin-libev.c)
+SET_TARGET_PROPERTIES(couchbase_libev
+    PROPERTIES
+    PREFIX "lib"
+    IMPORT_PREFIX "lib"
+    COMPILE_FLAGS "${CMAKE_C_FLAGS} ${CMAKE_CORE_CFLAGS} -std=gnu99")
+TARGET_LINK_LIBRARIES(couchbase_libev ${LIBEV_LIBRARIES})
+INCLUDE_DIRECTORIES(AFTER ${LIBEV_INCLUDE_DIR})
+
+IF(HAVE_LIBEV4)
+    ADD_DEFINITIONS(-DHAVE_LIBEV4)
+ELSE()
+    ADD_DEFINITIONS(-DHAVE_LIBEV3)
+ENDIF()
+
+INSTALL(TARGETS
+    couchbase_libev
+    LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR})

data/ext/libcouchbase/plugins/io/libev/libev_io_opts.h

@@ -0,0 +1,66 @@
+/* -*- Mode: C; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *     Copyright 2011-2012 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.
+ */
+
+/**
+ * @file
+ * libev integration with libcouchbase
+ * @author Sergey Avseyev
+ */
+
+/**
+ * @ingroup lcb-io-plugin-api
+ * @defgroup lcb-libev libev
+ * @brief libev integration
+ *
+ * @details
+ * libcouchbase_create_libev_io_opts() allows you to create an instance
+ * of the ioopts that will utilize libev. You may either supply an event
+ * loop (if you'd like to add your own events into the loop), or it will
+ * create it's own.
+ *
+ * @addtogroup lcb-libev
+ * @{
+ */
+#ifndef LIBCOUCHBASE_LIBEV_IO_OPTS_H
+#define LIBCOUCHBASE_LIBEV_IO_OPTS_H 1
+
+#include <libcouchbase/couchbase.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+    /**
+     * Create an instance of an event handler that utilize libev for
+     * event notification.
+     *
+     * @param version Set this to 0. This may be used in the future to allow
+     *        variation on the third argument (`void*` currently).
+     * @param[out] io a pointer to a newly created and initialized event handler
+     * @param loop the event loop (struct ev_loop *) to hook use (please
+     *             note that you shouldn't reference the event loop from
+     *             multiple threads)
+     * @return status of the operation
+     */
+    LIBCOUCHBASE_API
+    lcb_error_t lcb_create_libev_io_opts(int version, lcb_io_opt_t *io, void *loop);
+#ifdef __cplusplus
+}
+#endif
+
+/**@}*/
+#endif