There's quite a bit of user code which calls io->run_event_loop and io->stop_event_loop.
These functions are largely private and are intended for use by libcouchbase itself. The fact that they are public API is only accidental, due to the fact that they are part of the iops structure.
These functions should never be called by user code:
1) They are a source of confusion (especially when mixed with lcb_wait)
2) They prevent any kind of wrapping/sanity logic done by lcb_wait (some already exists, and some can be implemented in future versions)
The following should be done
1) Remove the iops structure definition from being included by the main header file. Thus, #include <libcouchbase/couchbase.h> should not allow a dereference of the iops structure. Rather the iops structure should be defined in a new header file (iops.h) - so that users who want to explicitly manipulate and write event loop plugins can include it, but should otherwise not be present in 'user' code. types.h should include a predeclaration of the structure so that it may still be passed around as a simple pointer value.
2) Document the purpose of run_event_loop/stop_event_loop. Make it very clear that lcb_wait should be used in all synchronous use cases. If we have any examples using run_event_loop/stop_event_loop, remove them.
3) [ Optional? ] - In order to further discourage users from using these functions, throw a compiler warning/error for those functions unless LIBCOUCHBASE_INTERNAL is defined - tbd