couchbase 1.2.1 → 1.2.2

data/couchbase.gemspec

@@ -38,13 +38,11 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'yaji', '~> 0.3.2'
   s.add_runtime_dependency 'multi_json', '~> 1.0'
 
-  s.add_development_dependency 'rake', '~> 0.8.7'
+  s.add_development_dependency 'rake'
   s.add_development_dependency 'minitest'
   s.add_development_dependency 'rake-compiler', '>= 0.7.5'
-  s.add_development_dependency 'rdiscount'
-  s.add_development_dependency 'yard'
-  s.add_development_dependency 'yard-xml'
   s.add_development_dependency 'mini_portile'
   s.add_development_dependency 'yajl-ruby', '~> 1.1.0'
   s.add_development_dependency 'active_support'
+  s.add_development_dependency 'eventmachine'
 end

data/examples/chat-em/Gemfile

@@ -0,0 +1,7 @@
+source :rubygems
+
+gem 'eventmachine'
+
+# couchbase dependencies
+gem 'yaji'
+gem 'multi_json'

data/examples/chat-em/README.markdown

@@ -0,0 +1,45 @@
+# Chat Demo
+
+This is simple demo of the chat built on EventMachine, and using
+Couchbase to store logs.
+
+# Quick Start and Usage
+
+Navigate to the example directory and install dependencies:
+
+    $ cd examples/chat-em
+    $ bundle install
+
+Execute the server
+
+    $ ruby ./server.rb
+    Hi, this is simple chat server based on EventMachine.
+    To join, just use your telnet or netcat clients to connect to
+    port 9999 on this machine. Press Ctrl-C to stop it.
+
+Use telnet to join the chat
+
+    $ telnet localhost 9999
+    Trying 127.0.0.1...
+    Connected to localhost.
+    Escape character is '^]'.
+    *** What is your name?
+    avsej
+    *** Hi, avsej!
+    Hi everyone in this chat
+
+The server will broadcast all your messages and record any event to
+the Couchbase server. If your server hosted not on the localhost or
+using bucket different from "default" you might want to change the
+connection options at the bottom of the `server.rb`, for example in
+this case it will connect to the bucket "protected" with password
+"secret".
+
+    Couchbase.connection_options = {
+                :async => true,
+                :engine => :eventmachine,
+                :bucket => "protected",
+                :password => "secret"
+              }
+
+Happy hacking!

data/examples/chat-em/server.rb

@@ -0,0 +1,82 @@
+#!/usr/bin/env ruby
+["/../../lib", "/.."].each do |path|
+  $LOAD_PATH.unshift(File.expand_path(File.dirname(__FILE__) + path))
+end
+
+require 'bundler'
+Bundler.require
+
+require 'couchbase'
+
+class ChatServer < EM::Connection
+
+  @@clients = []
+
+  def log(message, author = nil)
+    Couchbase.bucket.incr("log:key", :initial => 1) do |res|
+      entry = {
+        'time' => Time.now.utc,
+        'author' => author || "[system]",
+        'message' => message
+      }
+      Couchbase.bucket.set("log:#{res.value}", entry)
+    end
+  end
+
+  def post_init
+    @username = nil
+    send_data("*** What is your name?\n")
+  end
+
+  def receive_data(data)
+    if @username
+      broadcast(data.strip, @username)
+    else
+      name = data.gsub(/\s+|[\[\]]/, '').strip[0..20]
+      if name.empty?
+        send_data("*** What is your name?\n")
+      else
+        @username = name
+        @@clients.push(self)
+        broadcast("#{@username} has joined")
+        send_data("*** Hi, #{@username}!\n")
+      end
+    end
+  end
+
+  def unbind
+    @@clients.delete(self)
+    broadcast("#{@username} has left") if @username
+  end
+
+  def broadcast(message, author = nil)
+    prefix = author ? "<#{@username}>" : "***"
+    log(message, author)
+    @@clients.each do |client|
+      unless client == self
+        client.send_data("#{prefix} #{message}\n")
+      end
+    end
+  end
+
+end
+
+EventMachine.run do
+  # hit Control + C to stop
+  Signal.trap("INT")  { EventMachine.stop }
+  Signal.trap("TERM") { EventMachine.stop }
+
+  Couchbase.connection_options = {:async => true, :engine => :eventmachine}
+  Couchbase.bucket.on_connect do |res|
+    if res.success?
+      puts(<<-MOTD.gsub(/^\s+/, ''))
+        Hi, this is simple chat server based on EventMachine.
+        To join, just use your telnet or netcat clients to connect to
+        port 9999 on this machine. Press Ctrl-C to stop it.
+      MOTD
+      EventMachine.start_server("0.0.0.0", 9999, ChatServer)
+    else
+      puts "Cannot connect to Couchbase Server: #{res.error}"
+    end
+  end
+end

data/ext/couchbase_ext/arguments.c

@@ -56,6 +56,7 @@ cb_params_touch_alloc(struct cb_params_st *params, lcb_size_t size)
 cb_params_touch_init_item(struct cb_params_st *params, lcb_size_t idx, VALUE key_obj, lcb_time_t exptime)
 {
     key_obj = cb_unify_key(params->bucket, key_obj, 1);
+    rb_ary_push(params->ensurance, key_obj);
     params->cmd.touch.items[idx].v.v0.key = RSTRING_PTR(key_obj);
     params->cmd.touch.items[idx].v.v0.nkey = RSTRING_LEN(key_obj);
     params->cmd.touch.items[idx].v.v0.exptime = exptime;
@@ -140,6 +141,7 @@ cb_params_remove_alloc(struct cb_params_st *params, lcb_size_t size)
 cb_params_remove_init_item(struct cb_params_st *params, lcb_size_t idx, VALUE key_obj, lcb_cas_t cas)
 {
     key_obj = cb_unify_key(params->bucket, key_obj, 1);
+    rb_ary_push(params->ensurance, key_obj);
     params->cmd.remove.items[idx].v.v0.key = RSTRING_PTR(key_obj);
     params->cmd.remove.items[idx].v.v0.nkey = RSTRING_LEN(key_obj);
     params->cmd.remove.items[idx].v.v0.cas = cas;
@@ -239,6 +241,8 @@ cb_params_store_init_item(struct cb_params_st *params, lcb_size_t idx,
         VALUE val = rb_any_to_s(value_obj);
         rb_raise(cb_eValueFormatError, "unable to convert value for key '%s' to string: %s", RSTRING_PTR(key_obj), RSTRING_PTR(val));
     }
+    rb_ary_push(params->ensurance, key_obj);
+    rb_ary_push(params->ensurance, value_obj);
     params->cmd.store.items[idx].v.v0.datatype = params->cmd.store.datatype;
     params->cmd.store.items[idx].v.v0.operation = params->cmd.store.operation;
     params->cmd.store.items[idx].v.v0.key = RSTRING_PTR(key_obj);
@@ -347,6 +351,7 @@ cb_params_get_init_item(struct cb_params_st *params, lcb_size_t idx,
         VALUE key_obj, lcb_time_t exptime)
 {
     key_obj = cb_unify_key(params->bucket, key_obj, 1);
+    rb_ary_push(params->ensurance, key_obj);
     if (params->cmd.get.replica) {
         params->cmd.get.items_gr[idx].v.v0.key = RSTRING_PTR(key_obj);
         params->cmd.get.items_gr[idx].v.v0.nkey = RSTRING_LEN(key_obj);
@@ -461,6 +466,7 @@ cb_params_arith_init_item(struct cb_params_st *params, lcb_size_t idx,
         VALUE key_obj, lcb_int64_t delta)
 {
     key_obj = cb_unify_key(params->bucket, key_obj, 1);
+    rb_ary_push(params->ensurance, key_obj);
     params->cmd.arith.items[idx].v.v0.key = RSTRING_PTR(key_obj);
     params->cmd.arith.items[idx].v.v0.nkey = RSTRING_LEN(key_obj);
     params->cmd.arith.items[idx].v.v0.delta = delta * params->cmd.arith.sign;
@@ -565,6 +571,7 @@ cb_params_stats_init_item(struct cb_params_st *params, lcb_size_t idx,
         VALUE key_obj)
 {
     key_obj = cb_unify_key(params->bucket, key_obj, 1);
+    rb_ary_push(params->ensurance, key_obj);
     params->cmd.stats.items[idx].v.v0.name = RSTRING_PTR(key_obj);
     params->cmd.stats.items[idx].v.v0.nname = RSTRING_LEN(key_obj);
     params->npayload += RSTRING_LEN(key_obj);
@@ -616,6 +623,7 @@ cb_params_observe_alloc(struct cb_params_st *params, lcb_size_t size)
 cb_params_observe_init_item(struct cb_params_st *params, lcb_size_t idx, VALUE key_obj)
 {
     key_obj = cb_unify_key(params->bucket, key_obj, 1);
+    rb_ary_push(params->ensurance, key_obj);
     params->cmd.observe.items[idx].v.v0.key = RSTRING_PTR(key_obj);
     params->cmd.observe.items[idx].v.v0.nkey = RSTRING_LEN(key_obj);
     params->npayload += RSTRING_LEN(key_obj);
@@ -666,6 +674,7 @@ cb_params_unlock_alloc(struct cb_params_st *params, lcb_size_t size)
 cb_params_unlock_init_item(struct cb_params_st *params, lcb_size_t idx, VALUE key_obj, lcb_cas_t cas)
 {
     key_obj = cb_unify_key(params->bucket, key_obj, 1);
+    rb_ary_push(params->ensurance, key_obj);
     params->cmd.unlock.items[idx].v.v0.key = RSTRING_PTR(key_obj);
     params->cmd.unlock.items[idx].v.v0.nkey = RSTRING_LEN(key_obj);
     params->cmd.unlock.items[idx].v.v0.cas = cas;
@@ -733,6 +742,9 @@ cb_params_version_alloc(struct cb_params_st *params)
     void
 cb_params_destroy(struct cb_params_st *params)
 {
+    rb_ary_clear(params->ensurance);
+    params->ensurance = Qfalse;
+    params->args = Qfalse;
     switch (params->type) {
         case cb_cmd_get:
             _release_data_for(get);
@@ -765,22 +777,14 @@ cb_params_destroy(struct cb_params_st *params)
     }
 }
 
-struct build_params_st
-{
-    struct cb_params_st *params;
-    int argc;
-    VALUE argv;
-};
-
     static VALUE
 do_params_build(VALUE ptr)
 {
     VALUE opts;
     /* unpack arguments */
-    struct build_params_st *p = (struct build_params_st *)ptr;
-    struct cb_params_st *params = p->params;
-    int argc = p->argc;
-    VALUE argv = p->argv;
+    struct cb_params_st *params = (struct cb_params_st*)ptr;
+    int argc = RARRAY_LEN(params->args);
+    VALUE argv = params->args;
 
     /* extract options */
     if (argc > 1 && TYPE(RARRAY_PTR(argv)[argc-1]) == T_HASH) {
@@ -873,15 +877,12 @@ do_params_build(VALUE ptr)
 }
 
     void
-cb_params_build(struct cb_params_st *params, int argc, VALUE argv)
+cb_params_build(struct cb_params_st *params)
 {
     int fail = 0;
-    struct build_params_st args;
+    params->ensurance = rb_ary_new();
 
-    args.params = params;
-    args.argc = argc;
-    args.argv = argv;
-    rb_protect(do_params_build, (VALUE)&args, &fail);
+    rb_protect(do_params_build, (VALUE)params, &fail);
     if (fail) {
         cb_params_destroy(params);
         /* raise exception from protected block */

data/ext/couchbase_ext/arithmetic.c

@@ -22,7 +22,7 @@ cb_arithmetic_callback(lcb_t handle, const void *cookie, lcb_error_t error, cons
 {
     struct cb_context_st *ctx = (struct cb_context_st *)cookie;
     struct cb_bucket_st *bucket = ctx->bucket;
-    VALUE cas, key, val, *rv = ctx->rv, exc, res;
+    VALUE cas, key, val, exc, res;
     ID o;
 
     ctx->nqueries--;
@@ -35,7 +35,7 @@ cb_arithmetic_callback(lcb_t handle, const void *cookie, lcb_error_t error, cons
     if (exc != Qnil) {
         rb_ivar_set(exc, cb_id_iv_cas, cas);
         rb_ivar_set(exc, cb_id_iv_operation, o);
-        ctx->exception = cb_gc_protect(bucket, exc);
+        ctx->exception = exc;
     }
     val = ULL2NUM(resp->v.v0.value);
     if (bucket->async) {    /* asynchronous */
@@ -51,16 +51,16 @@ cb_arithmetic_callback(lcb_t handle, const void *cookie, lcb_error_t error, cons
     } else {                /* synchronous */
         if (NIL_P(exc)) {
             if (ctx->extended) {
-                rb_hash_aset(*rv, key, rb_ary_new3(2, val, cas));
+                rb_hash_aset(ctx->rv, key, rb_ary_new3(2, val, cas));
             } else {
-                rb_hash_aset(*rv, key, val);
+                rb_hash_aset(ctx->rv, key, val);
             }
         }
     }
     if (ctx->nqueries == 0) {
-        cb_gc_unprotect(bucket, ctx->proc);
+        ctx->proc = Qnil;
         if (bucket->async) {
-            free(ctx);
+            cb_context_free(ctx);
         }
     }
     (void)handle;
@@ -71,38 +71,30 @@ cb_bucket_arithmetic(int sign, int argc, VALUE *argv, VALUE self)
 {
     struct cb_bucket_st *bucket = DATA_PTR(self);
     struct cb_context_st *ctx;
-    VALUE args, rv, proc, exc;
+    VALUE rv, proc, exc;
     lcb_error_t err;
     struct cb_params_st params;
 
-    if (bucket->handle == NULL) {
-        rb_raise(cb_eConnectError, "closed connection");
+    if (!cb_bucket_connected_bang(bucket, sign > 0 ? cb_sym_increment : cb_sym_decrement)) {
+        return Qnil;
     }
-    rb_scan_args(argc, argv, "0*&", &args, &proc);
+
+    memset(&params, 0, sizeof(struct cb_params_st));
+    rb_scan_args(argc, argv, "0*&", &params.args, &proc);
     if (!bucket->async && proc != Qnil) {
         rb_raise(rb_eArgError, "synchronous mode doesn't support callbacks");
     }
-    memset(&params, 0, sizeof(struct cb_params_st));
     params.type = cb_cmd_arith;
     params.bucket = bucket;
     params.cmd.arith.sign = sign;
-    cb_params_build(&params, RARRAY_LEN(args), args);
-    ctx = calloc(1, sizeof(struct cb_context_st));
-    if (ctx == NULL) {
-        rb_raise(cb_eClientNoMemoryError, "failed to allocate memory for context");
-    }
-    rv = rb_hash_new();
-    ctx->rv = &rv;
-    ctx->bucket = bucket;
-    ctx->proc = cb_gc_protect(bucket, proc);
-    ctx->exception = Qnil;
-    ctx->nqueries = params.cmd.arith.num;
+    cb_params_build(&params);
+    ctx = cb_context_alloc_common(bucket, proc, params.cmd.arith.num);
     err = lcb_arithmetic(bucket->handle, (const void *)ctx,
             params.cmd.arith.num, params.cmd.arith.ptr);
     cb_params_destroy(&params);
     exc = cb_check_error(err, "failed to schedule arithmetic request", Qnil);
     if (exc != Qnil) {
-        free(ctx);
+        cb_context_free(ctx);
         rb_exc_raise(exc);
     }
     bucket->nbytes += params.npayload;
@@ -115,9 +107,9 @@ cb_bucket_arithmetic(int sign, int argc, VALUE *argv, VALUE self)
             lcb_wait(bucket->handle);
         }
         exc = ctx->exception;
-        free(ctx);
+        rv = ctx->rv;
+        cb_context_free(ctx);
         if (exc != Qnil) {
-            cb_gc_unprotect(bucket, exc);
             rb_exc_raise(exc);
         }
         if (params.cmd.store.num > 1) {

data/ext/couchbase_ext/bucket.c

@@ -17,6 +17,24 @@
 
 #include "couchbase_ext.h"
 
+    static VALUE
+trigger_on_connect_callback(VALUE self)
+{
+    struct cb_bucket_st *bucket = DATA_PTR(self);
+    VALUE on_connect_proc = bucket->on_connect_proc;
+    if (RTEST(on_connect_proc)) {
+        VALUE res = rb_class_new_instance(0, NULL, cb_cResult);
+        rb_ivar_set(res, cb_id_iv_error, bucket->exception);
+        bucket->exception = Qnil;
+        rb_ivar_set(res, cb_id_iv_operation, cb_sym_connect);
+        rb_ivar_set(res, cb_id_iv_value, self);
+        return rb_funcall(on_connect_proc, cb_id_call, 1, res);
+    } else {
+        bucket->trigger_connect_cb_on_set = 1;
+        return Qnil;
+    }
+}
+
     static void
 error_callback(lcb_t handle, lcb_error_t error, const char *errinfo)
 {
@@ -24,6 +42,20 @@ error_callback(lcb_t handle, lcb_error_t error, const char *errinfo)
 
     lcb_breakout(handle);
     bucket->exception = cb_check_error(error, errinfo, Qnil);
+    if (bucket->async && !bucket->connected) {
+        (void)trigger_on_connect_callback(bucket->self);
+    }
+}
+
+    static void
+configuration_callback(lcb_t handle, lcb_configuration_t config)
+{
+    struct cb_bucket_st *bucket = (struct cb_bucket_st *)lcb_get_cookie(handle);
+
+    if (config == LCB_CONFIGURATION_NEW) {
+        bucket->connected = 1;
+        (void)trigger_on_connect_callback(bucket->self);
+    }
 }
 
     void
@@ -32,12 +64,21 @@ cb_bucket_free(void *ptr)
     struct cb_bucket_st *bucket = ptr;
 
     if (bucket) {
+        bucket->destroying = 1;
         if (bucket->handle) {
             lcb_destroy(bucket->handle);
             lcb_destroy_io_ops(bucket->io);
         }
+        st_free_table(bucket->object_space);
+        xfree(bucket);
     }
-    xfree(bucket);
+}
+
+    static int
+cb_bucket_mark_object_i(st_index_t key, st_data_t value, st_data_t arg)
+{
+    ((mark_f)value)((void*)key, (struct cb_bucket_st*)arg);
+    return ST_CONTINUE;
 }
 
     void
@@ -54,8 +95,9 @@ cb_bucket_mark(void *ptr)
         rb_gc_mark(bucket->password);
         rb_gc_mark(bucket->exception);
         rb_gc_mark(bucket->on_error_proc);
+        rb_gc_mark(bucket->on_connect_proc);
         rb_gc_mark(bucket->key_prefix_val);
-        rb_gc_mark(bucket->object_space);
+        st_foreach(bucket->object_space, cb_bucket_mark_object_i, (st_data_t)bucket);
     }
 }
 
@@ -207,6 +249,26 @@ do_scan_connection_options(struct cb_bucket_st *bucket, int argc, VALUE *argv)
                     bucket->default_arith_init = NUM2ULL(arg);
                 }
             }
+            arg = rb_hash_aref(opts, cb_sym_engine);
+            if (arg != Qnil) {
+                if (arg == cb_sym_default) {
+                    bucket->engine = cb_sym_default;
+#ifndef _WIN32
+                } else if (arg == cb_sym_libev) {
+                    bucket->engine = cb_sym_libev;
+                } else if (arg == cb_sym_libevent) {
+                    bucket->engine = cb_sym_libevent;
+#ifdef BUILD_EVENTMACHINE_PLUGIN
+                } else if (arg == cb_sym_eventmachine) {
+                    bucket->engine = cb_sym_eventmachine;
+#endif
+#endif
+                } else {
+                    VALUE ins = rb_funcall(arg, rb_intern("inspect"), 0);
+                    rb_raise(rb_eArgError, "Couchbase: unknown engine %s", RSTRING_PTR(ins));
+                }
+            }
+            bucket->async = RTEST(rb_hash_aref(opts, cb_sym_async));
         } else {
             opts = Qnil;
         }
@@ -223,6 +285,17 @@ do_scan_connection_options(struct cb_bucket_st *bucket, int argc, VALUE *argv)
     rb_str_freeze(bucket->authority);
 }
 
+    static VALUE
+em_disconnect_block(VALUE unused, VALUE self)
+{
+    struct cb_bucket_st *bucket = DATA_PTR(self);
+    if (bucket->handle) {
+        return cb_bucket_disconnect(self);
+    }
+    (void)unused;
+    return Qnil;
+}
+
     static void
 do_connect(struct cb_bucket_st *bucket)
 {
@@ -234,24 +307,37 @@ do_connect(struct cb_bucket_st *bucket)
         lcb_destroy_io_ops(bucket->io);
         bucket->handle = NULL;
         bucket->io = NULL;
+        bucket->connected = 0;
     }
 
-#ifndef _WIN32
     {
         struct lcb_create_io_ops_st ciops;
         memset(&ciops, 0, sizeof(ciops));
-        ciops.version = 1;
-        ciops.v.v1.sofile = NULL;
-        ciops.v.v1.symbol = "cb_create_ruby_mt_io_opts";
-        ciops.v.v1.cookie = NULL;
-
-        err = lcb_create_io_ops(&bucket->io, &ciops);
-    }
+        ciops.version = 0;
+
+        if (bucket->engine == cb_sym_libevent) {
+            ciops.v.v0.type = LCB_IO_OPS_LIBEVENT;
+        } else if (bucket->engine == cb_sym_libev) {
+            ciops.v.v0.type = LCB_IO_OPS_LIBEV;
+        } else if (bucket->engine == cb_sym_eventmachine) {
+            ciops.version = 1;
+            ciops.v.v1.sofile = NULL;
+            ciops.v.v1.symbol = "cb_create_ruby_em_io_opts";
+            ciops.v.v1.cookie = bucket;
+        } else {
+#ifdef _WIN32
+            ciops.v.v0.type = LCB_IO_OPS_DEFAULT;
 #else
-    err = lcb_create_io_ops(&bucket->io, NULL);
+            ciops.version = 1;
+            ciops.v.v1.sofile = NULL;
+            ciops.v.v1.symbol = "cb_create_ruby_mt_io_opts";
+            ciops.v.v1.cookie = NULL;
 #endif
-    if (err != LCB_SUCCESS) {
-        rb_exc_raise(cb_check_error(err, "failed to create IO instance", Qnil));
+        }
+        err = lcb_create_io_ops(&bucket->io, &ciops);
+        if (err != LCB_SUCCESS) {
+            rb_exc_raise(cb_check_error(err, "failed to create IO instance", Qnil));
+        }
     }
 
     memset(&create_opts, 0, sizeof(struct lcb_create_st));
@@ -279,6 +365,7 @@ do_connect(struct cb_bucket_st *bucket)
     (void)lcb_set_http_data_callback(bucket->handle, cb_http_data_callback);
     (void)lcb_set_observe_callback(bucket->handle, cb_observe_callback);
     (void)lcb_set_unlock_callback(bucket->handle, cb_unlock_callback);
+    (void)lcb_set_configuration_callback(bucket->handle, configuration_callback);
 
     if (bucket->timeout > 0) {
         lcb_set_timeout(bucket->handle, bucket->timeout);
@@ -294,13 +381,19 @@ do_connect(struct cb_bucket_st *bucket)
         rb_exc_raise(cb_check_error(err, "failed to connect libcouchbase instance to server", Qnil));
     }
     bucket->exception = Qnil;
-    lcb_wait(bucket->handle);
-    if (bucket->exception != Qnil) {
-        lcb_destroy(bucket->handle);
-        lcb_destroy_io_ops(bucket->io);
-        bucket->handle = NULL;
-        bucket->io = NULL;
-        rb_exc_raise(bucket->exception);
+    if (bucket->engine == cb_sym_eventmachine && !bucket->async_disconnect_hook_set) {
+        bucket->async_disconnect_hook_set = 1;
+        rb_block_call(em_m, cb_id_add_shutdown_hook, 0, NULL, em_disconnect_block, bucket->self);
+    }
+    if (!bucket->async) {
+        lcb_wait(bucket->handle);
+        if (bucket->exception != Qnil) {
+            lcb_destroy(bucket->handle);
+            lcb_destroy_io_ops(bucket->io);
+            bucket->handle = NULL;
+            bucket->io = NULL;
+            rb_exc_raise(bucket->exception);
+        }
     }
 }
 
@@ -374,6 +467,17 @@ cb_bucket_alloc(VALUE klass)
  *     non positive number forces creation missing keys with given default
  *     value. Setting it to +true+ will use zero as initial value. (see
  *     {Bucket#incr} and {Bucket#decr}).
+ *   @option options [Symbol] :engine (:default) the IO engine to use
+ *     Currently following engines are supported:
+ *     :default      :: Built-in engine (multi-thread friendly)
+ *     :libevent     :: libevent IO plugin from libcouchbase (optional)
+ *     :libev        :: libev IO plugin from libcouchbase (optional)
+ *     :eventmachine :: EventMachine plugin (builtin, but requires EM gem and ruby 1.9+)
+ *   @option options [true, false] :async (false) If true, the
+ *     connection instance will be considered always asynchronous and
+ *     IO interaction will be occured only when {Couchbase::Bucket#run}
+ *     called. See {Couchbase::Bucket#on_connect} to hook your code
+ *     after the instance will be connected.
  *
  * @example Initialize connection using default options
  *   Couchbase.new
@@ -406,14 +510,13 @@ cb_bucket_init(int argc, VALUE *argv, VALUE self)
     bucket->self = self;
     bucket->exception = Qnil;
     bucket->type = LCB_TYPE_BUCKET;
-    bucket->hostname = rb_str_new2("localhost");
+    bucket->hostname = cb_vStrLocalhost;
     bucket->port = 8091;
     bucket->pool = cb_vStrDefault;
-    rb_str_freeze(bucket->pool);
     bucket->bucket = cb_vStrDefault;
-    rb_str_freeze(bucket->bucket);
     bucket->username = Qnil;
     bucket->password = Qnil;
+    bucket->engine = cb_sym_default;
     bucket->async = 0;
     bucket->quiet = 0;
     bucket->default_ttl = 0;
@@ -421,11 +524,16 @@ cb_bucket_init(int argc, VALUE *argv, VALUE self)
     bucket->default_format = cb_sym_document;
     bucket->default_observe_timeout = 2500000;
     bucket->on_error_proc = Qnil;
+    bucket->on_connect_proc = Qnil;
     bucket->timeout = 0;
     bucket->environment = cb_sym_production;
     bucket->key_prefix_val = Qnil;
     bucket->node_list = Qnil;
-    bucket->object_space = rb_hash_new();
+    bucket->object_space = st_init_numtable();
+    bucket->destroying = 0;
+    bucket->connected = 0;
+    bucket->on_connect_proc = Qnil;
+    bucket->async_disconnect_hook_set = 0;
 
     do_scan_connection_options(bucket, argc, argv);
     do_connect(bucket);
@@ -467,6 +575,7 @@ cb_bucket_init_copy(VALUE copy, VALUE orig)
     copy_b->bucket = orig_b->bucket;
     copy_b->username = orig_b->username;
     copy_b->password = orig_b->password;
+    copy_b->engine = orig_b->engine;
     copy_b->async = orig_b->async;
     copy_b->quiet = orig_b->quiet;
     copy_b->default_format = orig_b->default_format;
@@ -475,10 +584,17 @@ cb_bucket_init_copy(VALUE copy, VALUE orig)
     copy_b->environment = orig_b->environment;
     copy_b->timeout = orig_b->timeout;
     copy_b->exception = Qnil;
+    copy_b->async_disconnect_hook_set = 0;
     if (orig_b->on_error_proc != Qnil) {
         copy_b->on_error_proc = rb_funcall(orig_b->on_error_proc, cb_id_dup, 0);
     }
+    if (orig_b->on_connect_proc != Qnil) {
+        copy_b->on_connect_proc = rb_funcall(orig_b->on_connect_proc, cb_id_dup, 0);
+    }
     copy_b->key_prefix_val = orig_b->key_prefix_val;
+    copy_b->object_space = st_init_numtable();
+    copy_b->destroying = 0;
+    copy_b->connected = 0;
 
     do_connect(copy_b);
 
@@ -529,7 +645,7 @@ cb_bucket_reconnect(int argc, VALUE *argv, VALUE self)
 cb_bucket_connected_p(VALUE self)
 {
     struct cb_bucket_st *bucket = DATA_PTR(self);
-    return bucket->handle ? Qtrue : Qfalse;
+    return (bucket->handle && bucket->connected) ? Qtrue : Qfalse;
 }
 
 /* Document-method: async?
@@ -654,6 +770,51 @@ cb_bucket_on_error_get(VALUE self)
     }
 }
 
+    static
+VALUE trigger_on_connect_callback_block(VALUE nil, VALUE self)
+{
+    (void)nil;
+    return trigger_on_connect_callback(self);
+}
+
+    VALUE
+cb_bucket_on_connect_set(VALUE self, VALUE val)
+{
+    struct cb_bucket_st *bucket = DATA_PTR(self);
+
+    if (rb_respond_to(val, cb_id_call)) {
+        bucket->on_connect_proc = val;
+        if (bucket->trigger_connect_cb_on_set) {
+            bucket->trigger_connect_cb_on_set = 0;
+            if (bucket->async) {
+                VALUE args[] = {INT2FIX(0)};
+                /* setup timer with zero interval to call on_connect
+                 * callback on the next tick */
+                rb_block_call(bucket->self, cb_id_create_timer, 1,
+                        args, trigger_on_connect_callback_block, bucket->self);
+            } else {
+                trigger_on_connect_callback(self);
+            }
+        }
+    } else {
+        bucket->on_connect_proc = Qnil;
+    }
+
+    return bucket->on_connect_proc;
+}
+
+    VALUE
+cb_bucket_on_connect_get(VALUE self)
+{
+    struct cb_bucket_st *bucket = DATA_PTR(self);
+
+    if (rb_block_given_p()) {
+        return cb_bucket_on_connect_set(self, rb_block_proc());
+    } else {
+        return bucket->on_connect_proc;
+    }
+}
+
     VALUE
 cb_bucket_timeout_get(VALUE self)
 {
@@ -947,7 +1108,7 @@ cb_bucket_inspect(VALUE self)
             rb_id2name(SYM2ID(bucket->default_format)),
             bucket->default_flags,
             bucket->quiet ? "true" : "false",
-            bucket->handle ? "true" : "false",
+            (bucket->handle && bucket->connected) ? "true" : "false",
             bucket->timeout);
     rb_str_buf_cat2(str, buf);
     if (RTEST(bucket->key_prefix_val)) {
@@ -978,12 +1139,14 @@ cb_maybe_do_loop(struct cb_bucket_st *bucket)
 do_run(VALUE *args)
 {
     VALUE self = args[0], opts = args[1], proc = args[2], exc;
+    VALUE was_async = args[3];
     struct cb_bucket_st *bucket = DATA_PTR(self);
 
     if (bucket->handle == NULL) {
         rb_raise(cb_eConnectError, "closed connection");
     }
-    if (bucket->async) {
+
+    if (bucket->running) {
         rb_raise(cb_eInvalidError, "nested #run");
     }
     bucket->threshold = 0;
@@ -996,12 +1159,29 @@ do_run(VALUE *args)
         }
     }
     bucket->async = 1;
-    cb_proc_call(bucket, proc, 1, self);
+    bucket->running = 1;
+    if (proc != Qnil) {
+        cb_proc_call(bucket, proc, 1, self);
+    }
+    if (bucket->exception != Qnil) {
+        exc = bucket->exception;
+        bucket->exception = Qnil;
+        if (was_async) {
+            cb_async_error_notify(bucket, exc);
+            /* XXX return here? */
+        } else {
+            rb_exc_raise(exc);
+        }
+    }
     do_loop(bucket);
     if (bucket->exception != Qnil) {
         exc = bucket->exception;
         bucket->exception = Qnil;
-        rb_exc_raise(exc);
+        if (!was_async) {
+            rb_exc_raise(exc);
+        }
+        /* async connections notified immediately from the callbacks
+         * via cb_async_error_notify() */
     }
     return Qnil;
 }
@@ -1012,7 +1192,9 @@ ensure_run(VALUE *args)
     VALUE self = args[0];
     struct cb_bucket_st *bucket = DATA_PTR(self);
 
-    bucket->async = 0;
+    bucket->running = 0;
+    bucket->async = args[3];
+    bucket->running = args[4];
     return Qnil;
 }
 
@@ -1054,6 +1236,12 @@ ensure_run(VALUE *args)
  *   end
  *   # all commands were executed and sent is 3 now
  *
+ * @example Use {Couchbase::Bucket#run} without block for async connection
+ *   c = Couchbase.new(:async => true)
+ *   c.run      # ensure that instance connected
+ *   c.set("foo", "bar"){|r| puts r.cas}
+ *   c.run
+ *
  * @return [nil]
  *
  * @raise [Couchbase::Error::Connect] if connection closed (see {Bucket#reconnect})
@@ -1061,11 +1249,17 @@ ensure_run(VALUE *args)
     VALUE
 cb_bucket_run(int argc, VALUE *argv, VALUE self)
 {
-    VALUE args[3];
+    struct cb_bucket_st *bucket = DATA_PTR(self);
+    VALUE args[5];
 
-    rb_need_block();
+    /* it is allowed to omit block for async connections */
+    if (!bucket->async) {
+        rb_need_block();
+    }
     args[0] = self;
     rb_scan_args(argc, argv, "01&", &args[1], &args[2]);
+    args[3] = bucket->async;
+    args[4] = bucket->running;
     rb_ensure(do_run, (VALUE)args, ensure_run, (VALUE)args);
     return Qnil;
 }
@@ -1115,6 +1309,7 @@ cb_bucket_disconnect(VALUE self)
         lcb_destroy_io_ops(bucket->io);
         bucket->handle = NULL;
         bucket->io = NULL;
+        bucket->connected = 0;
         return Qtrue;
     } else {
         rb_raise(cb_eConnectError, "closed connection");