Class: Couchbase::Bucket

Inherits:
Object
  • Object
show all
Defined in:
ext/couchbase_ext/couchbase_ext.c,
lib/couchbase/bucket.rb,
ext/couchbase_ext/couchbase_ext.c

Overview

This class in charge of all stuff connected to communication with Couchbase.

Since:

Defined Under Namespace

Classes: CouchRequest

Constant Summary

FMT_MASK =

Bitmask for flag bits responsible for format

0x03
FMT_DOCUMENT =

Document format. The (default) format supports most of ruby types which could be mapped to JSON data (hashes, arrays, strings, numbers). Future version will be able to run map/reduce queries on the values in the document form (hashes).

0x00
FMT_MARSHAL =

Marshal format. The format which supports transparent serialization of ruby objects with standard Marshal.dump and Marhal.load methods.

0x01
FMT_PLAIN =

Plain format. The format which force client don’t apply any conversions to the value, but it should be passed as String. It could be useful for building custom algorithms or formats. For example implement set: http://dustin.github.com/2011/02/17/memcached-set.html

0x02

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Bucket) initialize(url, options = {}) - (Bucket) initialize(options = {})

Initialize new Bucket.

Examples:

Initialize connection using default options

Couchbase.new

Select custom bucket

Couchbase.new(:bucket => 'foo')
Couchbase.new('http://localhost:8091/pools/default/buckets/foo')

Connect to protected bucket

Couchbase.new(:bucket => 'protected', :username => 'protected', :password => 'secret')
Couchbase.new('http://localhost:8091/pools/default/buckets/protected',
              :username => 'protected', :password => 'secret')

Use list of nodes, in case some nodes might be dead

Couchbase.new(:node_list => ['example.com:8091', 'example.org:8091', 'example.net'])

Overloads:

  • - (Bucket) initialize(url, options = {})

    Initialize bucket using URI of the cluster and options. It is possible to override some parts of URI using the options keys (e.g. :host or :port)

    Parameters:

    • url (String)

      The full URL of management API of the cluster.

    • options (Hash)

      The options for connection. See options definition below.

  • - (Bucket) initialize(options = {})

    Initialize bucket using options only.

    Parameters:

    • options (Hash)

      The options for operation for connection

    Options Hash (options):

    • :node_list (Array) — default: nil

      the list of nodes to connect to. If specified it takes precedence over :host option. The list must be array of strings in form of host names or host names with ports (in first case port 8091 will be used, see examples).

    • :host (String) — default: "localhost"

      the hostname or IP address of the node

    • :port (Fixnum) — default: 8091

      the port of the managemenent API

    • :pool (String) — default: "default"

      the pool name

    • :bucket (String) — default: "default"

      the bucket name

    • :default_ttl (Fixnum) — default: 0

      the TTL used by default during storing key-value pairs.

    • :default_flags (Fixnum) — default: 0

      the default flags.

    • :default_format (Symbol) — default: :document

      the format, which will be used for values by default. Note that changing format will amend flags. (see #default_format)

    • :username (String) — default: nil

      the user name to connect to the cluster. Used to authenticate on management API. The username could be skipped for protected buckets, the bucket name will be used instead.

    • :password (String) — default: nil

      the password of the user.

    • :quiet (true, false) — default: false

      the flag controlling if raising exception when the client executes operations on unexising keys. If it is true it will raise Error::NotFound exceptions. The default behaviour is to return nil value silently (might be useful in Rails cache).

    • :environment (Symbol) — default: :production

      the mode of the connection. Currently it influences only on design documents set. If the environment is :development, you will able to get design documents with ‘dev_’ prefix, otherwise (in :production mode) the library will hide them from you.

    • :key_prefix (String) — default: nil

      the prefix string which will be prepended to each key before sending out, and sripped before returning back to the application.

    • :timeout (Fixnum) — default: 2500000

      the timeout for IO operations (in microseconds)

    • :default_arithmetic_init (Fixnum, true) — default: 0

      the default initial value for arithmetic operations. Setting this option to any non positive number forces creation missing keys with given default value. Setting it to true will use zero as initial value. (see #incr and #decr).

Raises:

Since:

  • 1.0.0



401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
# File 'ext/couchbase_ext/bucket.c', line 401

VALUE
cb_bucket_init(int argc, VALUE *argv, VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);

    bucket->self = self;
    bucket->exception = Qnil;
    bucket->type = LCB_TYPE_BUCKET;
    bucket->hostname = rb_str_new2("localhost");
    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->async = 0;
    bucket->quiet = 0;
    bucket->default_ttl = 0;
    bucket->default_flags = 0;
    bucket->default_format = cb_sym_document;
    bucket->default_observe_timeout = 2500000;
    bucket->on_error_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();

    do_scan_connection_options(bucket, argc, argv);
    do_connect(bucket);

    return self;
}

Instance Attribute Details

- (String) authority (readonly)

The authority ("hostname:port") of the current node

Returns:

  • (String)

    host with port

See Also:

Since:

  • 1.0.0



759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
# File 'ext/couchbase_ext/bucket.c', line 759

VALUE
cb_bucket_authority_get(VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    VALUE old_hostname = bucket->hostname;
    uint16_t old_port = bucket->port;
    VALUE hostname = cb_bucket_hostname_get(self);
    cb_bucket_port_get(self);

    if (hostname != old_hostname || bucket->port != old_port) {
        char port_s[8];
        snprintf(port_s, sizeof(port_s), ":%u", bucket->port);
        bucket->authority = rb_str_dup(hostname);
        rb_str_cat2(bucket->authority, port_s);
        rb_str_freeze(bucket->authority);
    }
    return bucket->authority;
}

- (String) bucket (readonly) Also known as: name

The bucket name of the current connection

Returns:

  • (String)

    the bucket name

See Also:

Since:

  • 1.0.0



784
785
786
787
788
789
# File 'ext/couchbase_ext/bucket.c', line 784

VALUE
cb_bucket_bucket_get(VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    return bucket->bucket;
}

- (Fixnum, true) default_arithmetic_init

The initial value for arithmetic operations #incr and #decr. Setting this attribute will force aforementioned operations create keys unless they exists in the bucket and will use given value. You can also just specify true if you’d like just force key creation with zero default value.

Returns:

  • (Fixnum, true)

    The initial value for arithmetic operations #incr and #decr. Setting this attribute will force aforementioned operations create keys unless they exists in the bucket and will use given value. You can also just specify true if you’d like just force key creation with zero default value.

Since:

  • 1.2.0



677
678
679
680
681
682
# File 'ext/couchbase_ext/bucket.c', line 677

VALUE
cb_bucket_default_arithmetic_init_get(VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    return ULL2NUM(bucket->default_arith_init);
}

- (Fixnum) default_flags

Note:

Amending format bit will also change #default_format value

Default flags for new values.

The library reserves last two lower bits to store the format of the value. The can be masked via FMT_MASK constant.

Examples:

Selecting format bits

connection.default_flags & Couchbase::Bucket::FMT_MASK

Set user defined bits

connection.default_flags |= 0x6660

Returns:

  • (Fixnum)

    the effective flags

Since:

  • 1.0.0



581
582
583
584
585
586
# File 'ext/couchbase_ext/bucket.c', line 581

VALUE
cb_bucket_default_flags_get(VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    return ULONG2NUM(bucket->default_flags);
}

- (Symbol) default_format

Note:

Amending default_format will also change #default_flags value

Default format for new values.

It uses flags field to store the format. It accepts either the Symbol (+:document+, :marshal, :plain) or Fixnum (use constants FMT_DOCUMENT, FMT_MARSHAL, FMT_PLAIN) and silently ignores all other value.

Here is some notes regarding how to choose the format:

  • :document (default) format supports most of ruby types which could be mapped to JSON data (hashes, arrays, strings, numbers). Future version will be able to run map/reduce queries on the values in the document form (hashes).
  • :plain format if you no need any conversions to be applied to your data, but your data should be passed as String. It could be useful for building custom algorithms or formats. For example implement set: http://dustin.github.com/2011/02/17/memcached-set.html
  • :marshal format if you’d like to transparently serialize your ruby object with standard Marshal.dump and Marhal.load methods.

Examples:

Selecting plain format using cb_symbol

connection.format = :document

Selecting plain format using Fixnum constant

connection.format = Couchbase::Bucket::FMT_PLAIN

Returns:

  • (Symbol)

    the effective format

See Also:

Since:

  • 1.0.0



598
599
600
601
602
603
# File 'ext/couchbase_ext/bucket.c', line 598

VALUE
cb_bucket_default_format_get(VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    return bucket->default_format;
}

- (Fixnum) default_observe_timeout

The default timeout value for #observe_and_wait operation in microseconds

Returns:

  • (Fixnum)

Since:

  • 1.2.0.dp6



873
874
875
876
877
878
# File 'ext/couchbase_ext/bucket.c', line 873

VALUE
cb_bucket_default_observe_timeout_get(VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    return INT2FIX(bucket->default_observe_timeout);
}

- (Symbol) environment (readonly)

The environment of the connection (+:development+ or :production)

Returns:

  • (Symbol)

Since:

  • 1.2.0



839
840
841
842
843
844
# File 'ext/couchbase_ext/bucket.c', line 839

VALUE
cb_bucket_environment_get(VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    return bucket->environment;
}

- (String) hostname (readonly)

The hostname of the current node

Returns:

  • (String)

    the host name of the management interface (default: "localhost")

See Also:

Since:

  • 1.0.0



721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
# File 'ext/couchbase_ext/bucket.c', line 721

VALUE
cb_bucket_hostname_get(VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);

    if (bucket->handle) {
        const char * host = lcb_get_host(bucket->handle);
        unsigned long len = RSTRING_LEN(bucket->hostname);
        if (len != strlen(host) || strncmp(RSTRING_PTR(bucket->hostname), host, len) != 0) {
            bucket->hostname = STR_NEW_CSTR(host);
            rb_str_freeze(bucket->hostname);
        }
    }
    return bucket->hostname;
}

- (String) key_prefix

The library will prepend key_prefix to each key to provide simple namespacing.

Returns:

  • (String)

    The library will prepend key_prefix to each key to provide simple namespacing.

Since:

  • 1.2.0.dp5



698
699
700
701
702
703
# File 'ext/couchbase_ext/bucket.c', line 698

VALUE
cb_bucket_key_prefix_get(VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    return bucket->key_prefix_val;
}

- (Fixnum) num_replicas (readonly)

The numbers of the replicas for each node in the cluster

Returns:

  • (Fixnum)

Since:

  • 1.2.0.dp6



853
854
855
856
857
858
859
860
861
862
863
# File 'ext/couchbase_ext/bucket.c', line 853

VALUE
cb_bucket_num_replicas_get(VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    int32_t nr = lcb_get_num_replicas(bucket->handle);
    if (nr < 0) {
        return Qnil;
    } else {
        return INT2FIX(nr);
    }
}

- (Proc) on_error {|op, key, exc| ... }

Error callback for asynchronous mode.

This callback is using to deliver exceptions in asynchronous mode.

Examples:

Using lambda syntax

connection = Couchbase.new(:async => true)
connection.on_error = lambda {|op, key, exc| ... }
connection.run do |conn|
  conn.set("foo", "bar")
end

Using block syntax

connection = Couchbase.new(:async => true)
connection.on_error {|op, key, exc| ... }
...

Yield Parameters:

  • op (Symbol)

    The operation caused the error

  • key (String)

    The key which cause the error or nil

  • exc (Exception)

    The exception instance

Returns:

  • (Proc)

    the effective callback

Since:

  • 1.0.0



645
646
647
648
649
650
651
652
653
654
655
# File 'ext/couchbase_ext/bucket.c', line 645

VALUE
cb_bucket_on_error_get(VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);

    if (rb_block_given_p()) {
        return cb_bucket_on_error_set(self, rb_block_proc());
    } else {
        return bucket->on_error_proc;
    }
}

- (String) password (readonly)

The password used to connect to the cluster

Returns:

  • (String)

    the password for protected buckets

Since:

  • 1.0.0



824
825
826
827
828
829
# File 'ext/couchbase_ext/bucket.c', line 824

VALUE
cb_bucket_password_get(VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    return bucket->password;
}

- (String) pool (readonly)

The pool name of the current connection

Returns:

  • (String)

    the pool name (usually "default")

See Also:

Since:

  • 1.0.0



797
798
799
800
801
802
# File 'ext/couchbase_ext/bucket.c', line 797

VALUE
cb_bucket_pool_get(VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    return bucket->pool;
}

- (Fixnum) port (readonly)

The port of the current node

Returns:

  • (Fixnum)

    the port number of the management interface (default: 8091)

See Also:

Since:

  • 1.0.0



743
744
745
746
747
748
749
750
751
# File 'ext/couchbase_ext/bucket.c', line 743

VALUE
cb_bucket_port_get(VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    if (bucket->handle) {
        bucket->port = atoi(lcb_get_port(bucket->handle));
    }
    return UINT2NUM(bucket->port);
}

- (true, false) quiet Also known as: quiet?

Flag specifying behaviour for operations on missing keys

If it is true, the operations will silently return nil or false instead of raising Error::NotFound.

Examples:

Hiding cache miss (considering "miss" key is not stored)

connection.quiet = true
connection.get("miss")     #=> nil

Raising errors on miss (considering "miss" key is not stored)

connection.quiet = false
connection.get("miss")     #=> will raise Couchbase::Error::NotFound

Returns:

  • (true, false)

Since:

  • 1.0.0



563
564
565
566
567
568
# File 'ext/couchbase_ext/bucket.c', line 563

VALUE
cb_bucket_quiet_get(VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    return bucket->quiet ? Qtrue : Qfalse;
}

- (Fixnum) timeout

The timeout for the operations in microseconds. The client will raise Error::Timeout exception for all commands which weren’t completed in given timeslot.

Returns:

  • (Fixnum)

    The timeout for the operations in microseconds. The client will raise Error::Timeout exception for all commands which weren’t completed in given timeslot.

Since:

  • 1.1.0



657
658
659
660
661
662
# File 'ext/couchbase_ext/bucket.c', line 657

VALUE
cb_bucket_timeout_get(VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    return ULONG2NUM(bucket->timeout);
}

- (String) url (readonly)

The config url for this connection.

Generally it is the bootstrap URL, but it could be different after cluster upgrade. This url is used to fetch the cluster configuration.

Returns:

  • (String)

    the address of the cluster management interface

Since:

  • 1.0.0



902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
# File 'ext/couchbase_ext/bucket.c', line 902

VALUE
cb_bucket_url_get(VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    VALUE str;

    (void)cb_bucket_authority_get(self);
    str = rb_str_buf_new2("http://");
    rb_str_append(str, bucket->authority);
    rb_str_buf_cat2(str, "/pools/");
    rb_str_append(str, bucket->pool);
    rb_str_buf_cat2(str, "/buckets/");
    rb_str_append(str, bucket->bucket);
    rb_str_buf_cat2(str, "/");
    return str;
}

- (String) username (readonly)

The user name used to connect to the cluster

Returns:

  • (String)

    the username for protected buckets (usually matches the bucket name)

See Also:

Since:

  • 1.0.0



811
812
813
814
815
816
# File 'ext/couchbase_ext/bucket.c', line 811

VALUE
cb_bucket_username_get(VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    return bucket->username;
}

Instance Method Details

- (Fixnum) add(key, value, options = {}) {|ret| ... }

Add the item to the database, but fail if the object exists already

The CAS value of the object.

Examples:

Add the same key twice

c.add("foo", "bar")  #=> stored successully
c.add("foo", "baz")  #=> will raise Couchbase::Error::KeyExists: failed to store value (key="foo", error=0x0c)

Ensure that the key will be persisted at least on the one node

c.add("foo", "bar", :observe => {:persisted => 1})

Parameters:

  • key (String, Symbol)

    Key used to reference the value.

  • value (Object)

    Value to be stored

  • options (Hash)

    Options for operation.

Options Hash (options):

  • :ttl (Fixnum) — default: self.default_ttl

    Expiry time for key. Values larger than 30*24*60*60 seconds (30 days) are interpreted as absolute times (from the epoch).

  • :flags (Fixnum) — default: self.default_flags

    Flags for storage options. Flags are ignored by the server but preserved for use by the client. For more info see #default_flags.

  • :format (Symbol) — default: self.default_format

    The representation for storing the value in the bucket. For more info see #default_format.

  • :cas (Fixnum)

    The CAS value for an object. This value created on the server and is guaranteed to be unique for each value of a given key. This value is used to provide simple optimistic concurrency control when multiple clients or threads try to update an item simultaneously.

  • :observe (Hash)

    Apply persistence condition before returning result. When this option specified the library will observe given condition. See #observe_and_wait.

Yield Parameters:

  • ret (Result)

    the result of operation in asynchronous mode (valid attributes: error, operation, key).

Returns:

  • (Fixnum)

    The CAS value of the object.

Raises:

Since:

  • 1.0.0



322
323
324
325
326
# File 'ext/couchbase_ext/store.c', line 322

VALUE
cb_bucket_add(int argc, VALUE *argv, VALUE self)
{
    return cb_bucket_store(LCB_ADD, argc, argv, self);
}

- (Fixnum) append(key, value, options = {})

Note:

This operation is kind of data-aware from server point of view. This mean that the server treats value as binary stream and just perform concatenation, therefore it won’t work with :marshal and :document formats, because of lack of knowledge how to merge values in these formats. See #cas for workaround.

Append this object to the existing object

The CAS value of the object.

Examples:

Simple append

c.set("foo", "aaa")
c.append("foo", "bbb")
c.get("foo")           #=> "aaabbb"

Implementing sets using append

def set_add(key, *values)
  encoded = values.flatten.map{|v| "+#{v} "}.join
  append(key, encoded)
end

def set_remove(key, *values)
  encoded = values.flatten.map{|v| "-#{v} "}.join
  append(key, encoded)
end

def set_get(key)
  encoded = get(key)
  ret = Set.new
  encoded.split(' ').each do |v|
    op, val = v[0], v[1..-1]
    case op
    when "-"
      ret.delete(val)
    when "+"
      ret.add(val)
    end
  end
  ret
end

Using optimistic locking. The operation will fail on CAS mismatch

ver = c.set("foo", "aaa")
c.append("foo", "bbb", :cas => ver)

Ensure that the key will be persisted at least on the one node

c.append("foo", "bar", :observe => {:persisted => 1})

Parameters:

  • key (String, Symbol)

    Key used to reference the value.

  • value (Object)

    Value to be stored

  • options (Hash)

    Options for operation.

Options Hash (options):

  • :cas (Fixnum)

    The CAS value for an object. This value created on the server and is guaranteed to be unique for each value of a given key. This value is used to provide simple optimistic concurrency control when multiple clients or threads try to update an item simultaneously.

  • :format (Symbol) — default: self.default_format

    The representation for storing the value in the bucket. For more info see #default_format.

  • :observe (Hash)

    Apply persistence condition before returning result. When this option specified the library will observe given condition. See #observe_and_wait.

Returns:

  • (Fixnum)

    The CAS value of the object.

Raises:

Since:

  • 1.0.0



450
451
452
453
454
# File 'ext/couchbase_ext/store.c', line 450

VALUE
cb_bucket_append(int argc, VALUE *argv, VALUE self)
{
    return cb_bucket_store(LCB_APPEND, argc, argv, self);
}

- (true, ...) async?

Check whether the connection asynchronous.

By default all operations are synchronous and block waiting for results, but you can make them asynchronous and run event loop explicitly. (see #run)

Examples:

Return value of #get operation depending on async flag

connection = Connection.new
connection.async?      #=> false

connection.run do |conn|
  conn.async?          #=> true
end

Returns:

  • (true, false)

    true if the connection if asynchronous

  • (Boolean)

See Also:

Since:

  • 1.0.0



556
557
558
559
560
561
# File 'ext/couchbase_ext/bucket.c', line 556

VALUE
cb_bucket_async_p(VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    return bucket->async ? Qtrue : Qfalse;
}

- (Fixnum) cas(key, options = {}) {|value| ... } Also known as: compare_and_swap

Compare and swap value.

Reads a key’s value from the server and yields it to a block. Replaces the key’s value with the result of the block as long as the key hasn’t been updated in the meantime, otherwise raises Error::KeyExists. CAS stands for "compare and swap", and avoids the need for manual key mutexing. Read more info here:

In asynchronous mode it will yield result twice, first for #get with Result#operation equal to :get and second time for #set with Result#operation equal to :set.

Examples:

Implement append to JSON encoded value

c.default_format = :document
c.set("foo", {"bar" => 1})
c.cas("foo") do |val|
  val["baz"] = 2
  val
end
c.get("foo")      #=> {"bar" => 1, "baz" => 2}

Append JSON encoded value asynchronously

c.default_format = :document
c.set("foo", {"bar" => 1})
c.run do
  c.cas("foo") do |val|
    case val.operation
    when :get
      val["baz"] = 2
      val
    when :set
      # verify all is ok
      puts "error: #{ret.error.inspect}" unless ret.success?
    end
  end
end
c.get("foo")      #=> {"bar" => 1, "baz" => 2}

Parameters:

  • key (String, Symbol)
  • options (Hash) (defaults to: {})

    the options for "swap" part

Options Hash (options):

  • :ttl (Fixnum) — default: self.default_ttl

    the time to live of this key

  • :format (Symbol) — default: self.default_format

    format of the value

  • :flags (Fixnum) — default: self.default_flags

    flags for this key

Yield Parameters:

  • value (Object, Result)

    old value in synchronous mode and Result object in asynchronous mode.

Yield Returns:

  • (Object)

    new value.

Returns:

  • (Fixnum)

    the CAS of new value

Raises:

  • (Couchbase::Error::KeyExists)

    if the key was updated before the the code in block has been completed (the CAS value has been changed).

  • (ArgumentError)

    if the block is missing for async mode

See Also:

Since:

  • 1.0.0



82
83
84
85
86
87
88
89
90
91
92
93
94
# File 'lib/couchbase/bucket.rb', line 82

def cas(key, options = {})
  if async?
    block = Proc.new
    get(key) do |ret|
      val = block.call(ret) # get new value from caller
      set(ret.key, val, options.merge(:cas => ret.cas, :flags => ret.flags), &block)
    end
  else
    val, flags, ver = get(key, :extended => true)
    val = yield(val) # get new value from caller
    set(key, val, options.merge(:cas => ver, :flags => flags))
  end
end

- (true, ...) connected?

Check whether the instance connected to the cluster.

Returns:

  • (true, false)

    true if the instance connected to the cluster

  • (Boolean)

Since:

  • 1.1.0



528
529
530
531
532
533
# File 'ext/couchbase_ext/bucket.c', line 528

VALUE
cb_bucket_connected_p(VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    return bucket->handle ? Qtrue : Qfalse;
}

- (Couchbase::Timer) create_periodic_timer(interval, &block)

Create and register periodic timer

Returns:



258
259
260
# File 'lib/couchbase/bucket.rb', line 258

def create_periodic_timer(interval, &block)
  Timer.new(self, interval, :periodic => true, &block)
end

- (Couchbase::Timer) create_timer(interval, &block)

Create and register one-shot timer

Returns:



251
252
253
# File 'lib/couchbase/bucket.rb', line 251

def create_timer(interval, &block)
  Timer.new(self, interval, &block)
end

- (Fixnum) decr(key, delta = 1, options = {}) {|ret| ... } Also known as: decrement

Note:

that server values stored and transmitted as unsigned numbers, therefore if you try to decrement negative or zero key, you will always get zero.

Decrement the value of an existing numeric key

The decrement methods reduce the value of a given key if the corresponding value can be parsed to an integer value. These operations are provided at a protocol level to eliminate the need to get, update, and reset a simple integer value in the database. It supports the use of an explicit offset value that will be used to reduce the stored value in the database.

The actual value of the key.

Examples:

Decrement key by one

c.decr("foo")

Decrement key by 50

c.decr("foo", 50)

Decrement key by one OR initialize with zero

c.decr("foo", :create => true)   #=> will return old-1 or 0

Decrement key by one OR initialize with three

c.decr("foo", 50, :initial => 3) #=> will return old-50 or 3

Decrement key and get its CAS value

val, cas = c.decr("foo", :extended => true)

Decrementing zero

c.set("foo", 0)
c.decrement("foo", 100500)   #=> 0

Decrementing negative value

c.set("foo", -100)
c.decrement("foo", 100500)   #=> 0

Asynchronous invocation

c.run do
  c.decr("foo") do |ret|
    ret.operation   #=> :decrement
    ret.success?    #=> true
    ret.key         #=> "foo"
    ret.value
    ret.cas
  end
end

Parameters:

  • key (String, Symbol)

    Key used to reference the value.

  • delta (Fixnum)

    Integer (up to 64 bits) value to decrement

  • options (Hash)

    Options for operation.

Options Hash (options):

  • :create (true, false) — default: false

    If set to true, it will initialize the key with zero value and zero flags (use :initial option to set another initial value). Note: it won’t decrement the missing value.

  • :initial (Fixnum) — default: 0

    Integer (up to 64 bits) value for missing key initialization. This option imply :create option is true.

  • :ttl (Fixnum) — default: self.default_ttl

    Expiry time for key. Values larger than 30*24*60*60 seconds (30 days) are interpreted as absolute times (from the epoch). This option ignored for existent keys.

  • :extended (true, false) — default: false

    If set to true, the operation will return tuple [value, cas], otherwise (by default) it returns just value.

Yield Parameters:

  • ret (Result)

    the result of operation in asynchronous mode (valid attributes: error, operation, key, value, cas).

Returns:

  • (Fixnum)

    the actual value of the key.

Raises:

Since:

  • 1.0.0



308
309
310
311
312
# File 'ext/couchbase_ext/arithmetic.c', line 308

VALUE
cb_bucket_decr(int argc, VALUE *argv, VALUE self)
{
    return cb_bucket_arithmetic(-1, argc, argv, self);
}

- (true, ...) delete(key, options = {})

Delete the specified key

The result of the operation

Examples:

Delete the key in quiet mode (default)

c.set("foo", "bar")
c.delete("foo")        #=> true
c.delete("foo")        #=> false

Delete the key verbosely

c.set("foo", "bar")
c.delete("foo", :quiet => false)   #=> true
c.delete("foo", :quiet => true)    #=> nil (default behaviour)
c.delete("foo", :quiet => false)   #=> will raise Couchbase::Error::NotFound

Delete the key with version check

ver = c.set("foo", "bar")          #=> 5992859822302167040
c.delete("foo", :cas => 123456)    #=> will raise Couchbase::Error::KeyExists
c.delete("foo", :cas => ver)       #=> true

Parameters:

  • key (String, Symbol)

    Key used to reference the value.

  • options (Hash)

    Options for operation.

Options Hash (options):

  • :quiet (true, false) — default: self.quiet

    If set to true, the operation won’t raise error for missing key, it will return nil. Otherwise it will raise error in synchronous mode. In asynchronous mode this option ignored.

  • :cas (Fixnum)

    The CAS value for an object. This value created on the server and is guaranteed to be unique for each value of a given key. This value is used to provide simple optimistic concurrency control when multiple clients or threads try to update/delete an item simultaneously.

Returns:

  • (true, false, Hash<String, Boolean>)

    the result of the operation

Raises:

Since:

  • 1.0.0



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
# File 'ext/couchbase_ext/delete.c', line 100

VALUE
cb_bucket_delete(int argc, VALUE *argv, VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    struct cb_context_st *ctx;
    VALUE rv, exc;
    VALUE args, proc;
    lcb_error_t err;
    struct cb_params_st params;

    if (bucket->handle == NULL) {
        rb_raise(cb_eConnectError, "closed connection");
    }
    rb_scan_args(argc, argv, "0*&", &args, &proc);
    if (!bucket->async && proc != Qnil) {
        rb_raise(rb_eArgError, "synchronous mode doesn't support callbacks");
    }
    rb_funcall(args, cb_id_flatten_bang, 0);
    memset(&params, 0, sizeof(struct cb_params_st));
    params.type = cb_cmd_remove;
    params.bucket = bucket;
    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");
    }
    ctx->quiet = params.cmd.remove.quiet;
    ctx->proc = cb_gc_protect(bucket, proc);
    rv = rb_hash_new();
    ctx->rv = &rv;
    ctx->bucket = bucket;
    ctx->exception = Qnil;
    ctx->nqueries = params.cmd.remove.num;
    err = lcb_remove(bucket->handle, (const void *)ctx,
            params.cmd.remove.num, params.cmd.remove.ptr);
    cb_params_destroy(&params);
    exc = cb_check_error(err, "failed to schedule delete request", Qnil);
    if (exc != Qnil) {
        free(ctx);
        rb_exc_raise(exc);
    }
    bucket->nbytes += params.npayload;
    if (bucket->async) {
        cb_maybe_do_loop(bucket);
        return Qnil;
    } else {
        if (ctx->nqueries > 0) {
            /* we have some operations pending */
            lcb_wait(bucket->handle);
        }
        exc = ctx->exception;
        free(ctx);
        if (exc != Qnil) {
            rb_exc_raise(cb_gc_unprotect(bucket, exc));
        }
        exc = bucket->exception;
        if (exc != Qnil) {
            bucket->exception = Qnil;
            rb_exc_raise(exc);
        }
        if (params.cmd.remove.num > 1) {
            return rv;  /* return as a hash {key => true, ...} */
        } else {
            VALUE vv = Qnil;
            rb_hash_foreach(rv, cb_first_value_i, (VALUE)&vv);
            return vv;
        }
        return rv;
    }
}

- (true, false) delete_design_doc(id, rev = nil)

Delete design doc with given id and revision.

Parameters:

  • id (String)

    Design document id. It might have ‘_design/’ prefix.

  • rev (String) (defaults to: nil)

    Document revision. It uses latest revision if rev parameter is nil.

Returns:

  • (true, false)

Since:

  • 1.2.0



182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
# File 'lib/couchbase/bucket.rb', line 182

def delete_design_doc(id, rev = nil)
  ddoc = design_docs[id.sub(/^_design\//, '')]
  unless ddoc
    yield nil if block_given?
    return nil
  end
  path = Utils.build_query(ddoc.id, :rev => rev || ddoc.meta['rev'])
  req = make_http_request(path, :method => :delete, :extended => true)
  rv = nil
  req.on_body do |res|
    rv = res
    val = MultiJson.load(res.value)
    if block_given?
      if res.success? && val['error']
        res.error = Error::View.new("delete_design_doc", val['error'])
      end
      yield(res)
    end
  end
  req.continue
  unless async?
    rv.success? or raise res.error
  end
end

- (Hash) design_docs

Fetch design docs stored in current bucket

Returns:

  • (Hash)

Since:

  • 1.2.0



102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
# File 'lib/couchbase/bucket.rb', line 102

def design_docs
  req = make_http_request("/pools/default/buckets/#{bucket}/ddocs",
                          :type => :management, :extended => true)
  docmap = {}
  req.on_body do |body|
    res = MultiJson.load(body.value)
    res["rows"].each do |obj|
      if obj['doc']
        obj['doc']['value'] = obj['doc'].delete('json')
      end
      doc = ViewRow.wrap(self, obj)
      key = doc.id.sub(/^_design\//, '')
      next if self.environment == :production && key =~ /dev_/
        docmap[key] = doc
    end
    yield(docmap) if block_given?
  end
  req.continue
  async? ? nil : docmap
end

- (true) disconnect

Close the connection to the cluster

Returns:

  • (true)

Raises:

Since:

  • 1.1.0



1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
# File 'ext/couchbase_ext/bucket.c', line 1108

VALUE
cb_bucket_disconnect(VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);

    if (bucket->handle) {
        lcb_destroy(bucket->handle);
        lcb_destroy_io_ops(bucket->io);
        bucket->handle = NULL;
        bucket->io = NULL;
        return Qtrue;
    } else {
        rb_raise(cb_eConnectError, "closed connection");
        return Qfalse;
    }
}

- (true) flush {|ret| ... }

Delete contents of the bucket

Examples:

Simple flush the bucket

c.flush    #=> true

Asynchronous flush

c.run do
  c.flush do |ret|
    ret.operation   #=> :flush
    ret.success?    #=> true
    ret.status      #=> 200
  end
end

Yield Parameters:

  • ret (Result)

    the object with error, status and operation attributes.

Returns:

  • (true)

    always return true (see raise section)

Raises:

See Also:

Since:

  • 1.2.0.beta



232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
# File 'lib/couchbase/bucket.rb', line 232

def flush
  if !async? && block_given?
    raise ArgumentError, "synchronous mode doesn't support callbacks"
  end
  req = make_http_request("/pools/default/buckets/#{bucket}/controller/doFlush",
                          :type => :management, :method => :post, :extended => true)
  res = nil
  req.on_body do |r|
    res = r
    res.instance_variable_set("@operation", :flush)
    yield(res) if block_given?
  end
  req.continue
  true
end

- (Object, ...) get(*keys, options = {}) {|ret| ... } - (Hash) get(keys, options = {}) Also known as: []

Obtain an object stored in Couchbase by given key.

Overloads:

  • - (Object, ...) get(*keys, options = {}) {|ret| ... }

    The value(s) (or tuples in extended mode) assiciated with the key.

    Examples:

    Get single value in quite mode (the default)

    c.get("foo")     #=> the associated value or nil
    

    Use alternative hash-like syntax

    c["foo"]         #=> the associated value or nil
    

    Get single value in verbose mode

    c.get("missing-foo", :quiet => false)  #=> raises Couchbase::NotFound
    c.get("missing-foo", :quiet => true)   #=> returns nil
    

    Get and touch single value. The key won’t be accessible after 10 seconds

    c.get("foo", :ttl => 10)
    

    Extended get

    val, flags, cas = c.get("foo", :extended => true)
    

    Get multiple keys

    c.get("foo", "bar", "baz")   #=> [val1, val2, val3]
    

    Get multiple keys with assembing result into the Hash

    c.get("foo", "bar", "baz", :assemble_hash => true)
    #=> {"foo" => val1, "bar" => val2, "baz" => val3}
    

    Extended get multiple keys

    c.get("foo", "bar", :extended => true)
    #=> {"foo" => [val1, flags1, cas1], "bar" => [val2, flags2, cas2]}
    

    Asynchronous get

    c.run do
      c.get("foo", "bar", "baz") do |res|
        ret.operation   #=> :get
        ret.success?    #=> true
        ret.key         #=> "foo", "bar" or "baz" in separate calls
        ret.value
        ret.flags
        ret.cas
      end
    end
    

    Get and lock key using default timeout

    c.get("foo", :lock => true)
    

    Determine lock timeout parameters

    c.stats.values_at("ep_getl_default_timeout", "ep_getl_max_timeout")
    #=> [{"127.0.0.1:11210"=>"15"}, {"127.0.0.1:11210"=>"30"}]
    

    Get and lock key using custom timeout

    c.get("foo", :lock => 3)
    

    Get and lock multiple keys using custom timeout

    c.get("foo", "bar", :lock => 3)
    

    Parameters:

    • keys (String, Symbol, Array)

      One or several keys to fetch

    • options (Hash)

      Options for operation.

    Options Hash (options):

    • :extended (true, false) — default: false

      If set to true, the operation will return tuple +[value, flags, cas]+, otherwise (by default) it returns just value.

    • :ttl (Fixnum) — default: self.default_ttl

      Expiry time for key. Values larger than 30*24*60*60 seconds (30 days) are interpreted as absolute times (from the epoch).

    • :quiet (true, false) — default: self.quiet

      If set to true, the operation won’t raise error for missing key, it will return nil. Otherwise it will raise error in synchronous mode. In asynchronous mode this option ignored.

    • :format (Symbol) — default: nil

      Explicitly choose the decoder for this key (+:plain+, :document, :marshal). See #default_format.

    • :lock (Fixnum, Boolean)

      Lock the keys for time span. If this parameter is true the key(s) will be locked for default timeout. Also you can use number to setup your own timeout in seconds. If it will be lower that zero or exceed the maximum, the server will use default value. You can determine actual default and maximum values calling #stats without arguments and inspecting keys "ep_getl_default_timeout" and "ep_getl_max_timeout" correspondingly. See overloaded hash syntax to specify custom timeout per each key.

    • :assemble_hash (true, false) — default: false

      Assemble Hash for results. Hash assembled automatically if :extended option is true or in case of "get and touch" multimple keys.

    • :replica (true, false) — default: false

      Read key from replica node. Options :ttl and :lock are not compatible with :replica.

    Yield Parameters:

    • ret (Result)

      the result of operation in asynchronous mode (valid attributes: error, operation, key, value, flags, cas).

    Returns:

    • (Object, Array, Hash)

      the value(s) (or tuples in extended mode) assiciated with the key.

    Raises:

  • - (Hash) get(keys, options = {})

    When the method receive hash map, it will behave like it receive list of keys (+keys.keys+), but also touch each key setting expiry time to the corresponding value. But unlike usual get this command always return hash map {key =&gt; value} or {key =&gt; [value, flags, cas]}.

    Examples:

    Get and touch multiple keys

    c.get("foo" => 10, "bar" => 20)   #=> {"foo" => val1, "bar" => val2}
    

    Extended get and touch multiple keys

    c.get({"foo" => 10, "bar" => 20}, :extended => true)
    #=> {"foo" => [val1, flags1, cas1], "bar" => [val2, flags2, cas2]}
    

    Get and lock multiple keys for chosen period in seconds

    c.get("foo" => 10, "bar" => 20, :lock => true)
    #=> {"foo" => val1, "bar" => val2}
    

    Parameters:

    • keys (Hash)

      Map key-ttl

    • options (Hash)

      Options for operation. (see options definition above)

    Returns:

    • (Hash)

      the values (or tuples in extended mode) assiciated with the keys.

See Also:

Since:

  • 1.0.0



220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
# File 'ext/couchbase_ext/get.c', line 220

VALUE
cb_bucket_get(int argc, VALUE *argv, VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    struct cb_context_st *ctx;
    VALUE args, rv, proc, exc;
    size_t ii;
    lcb_error_t err = LCB_SUCCESS;
    struct cb_params_st params;

    if (bucket->handle == NULL) {
        rb_raise(cb_eConnectError, "closed connection");
    }
    rb_scan_args(argc, argv, "0*&", &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_get;
    params.bucket = bucket;
    params.cmd.get.keys_ary = cb_gc_protect(bucket, rb_ary_new());
    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");
    }
    ctx->extended = params.cmd.get.extended;
    ctx->quiet = params.cmd.get.quiet;
    ctx->force_format = params.cmd.get.forced_format;
    ctx->proc = cb_gc_protect(bucket, proc);
    ctx->bucket = bucket;
    rv = rb_hash_new();
    ctx->rv = &rv;
    ctx->exception = Qnil;
    ctx->nqueries = params.cmd.get.num;
    if (params.cmd.get.replica) {
        err = lcb_get_replica(bucket->handle, (const void *)ctx,
                params.cmd.get.num, params.cmd.get.ptr_gr);
    } else {
        err = lcb_get(bucket->handle, (const void *)ctx,
                params.cmd.get.num, params.cmd.get.ptr);
    }
    cb_params_destroy(&params);
    cb_gc_unprotect(bucket, params.cmd.get.keys_ary);
    exc = cb_check_error(err, "failed to schedule get request", Qnil);
    if (exc != Qnil) {
        free(ctx);
        rb_exc_raise(exc);
    }
    bucket->nbytes += params.npayload;
    if (bucket->async) {
        cb_maybe_do_loop(bucket);
        return Qnil;
    } else {
        if (ctx->nqueries > 0) {
            /* we have some operations pending */
            lcb_wait(bucket->handle);
        }
        exc = ctx->exception;
        free(ctx);
        if (exc != Qnil) {
            cb_gc_unprotect(bucket, exc);
            rb_exc_raise(exc);
        }
        exc = bucket->exception;
        if (exc != Qnil) {
            bucket->exception = Qnil;
            rb_exc_raise(exc);
        }
        if (params.cmd.get.gat || params.cmd.get.assemble_hash ||
                (params.cmd.get.extended && (params.cmd.get.num > 1 || params.cmd.get.array))) {
            return rv;  /* return as a hash {key => [value, flags, cas], ...} */
        }
        if (params.cmd.get.num > 1 || params.cmd.get.array) {
            VALUE *keys_ptr, ret;
            ret = rb_ary_new();
            keys_ptr = RARRAY_PTR(params.cmd.get.keys_ary);
            for (ii = 0; ii < params.cmd.get.num; ++ii) {
                rb_ary_push(ret, rb_hash_aref(rv, keys_ptr[ii]));
            }
            return ret;  /* return as an array [value1, value2, ...] */
        } else {
            VALUE vv = Qnil;
            rb_hash_foreach(rv, cb_first_value_i, (VALUE)&vv);
            return vv;
        }
    }
}

- (Fixnum) incr(key, delta = 1, options = {}) {|ret| ... } Also known as: increment

Note:

that server values stored and transmitted as unsigned numbers, therefore if you try to store negative number and then increment or decrement it will cause overflow. (see "Integer overflow" example below)

Increment the value of an existing numeric key

The increment methods allow you to increase a given stored integer value. These are the incremental equivalent of the decrement operations and work on the same basis; updating the value of a key if it can be parsed to an integer. The update operation occurs on the server and is provided at the protocol level. This simplifies what would otherwise be a two-stage get and set operation.

The actual value of the key.

Examples:

Increment key by one

c.incr("foo")

Increment key by 50

c.incr("foo", 50)

Increment key by one OR initialize with zero

c.incr("foo", :create => true)   #=> will return old+1 or 0

Increment key by one OR initialize with three

c.incr("foo", 50, :initial => 3) #=> will return old+50 or 3

Increment key and get its CAS value

val, cas = c.incr("foo", :extended => true)

Integer overflow

c.set("foo", -100)
c.get("foo")           #=> -100
c.incr("foo")          #=> 18446744073709551517

Asynchronous invocation

c.run do
  c.incr("foo") do |ret|
    ret.operation   #=> :increment
    ret.success?    #=> true
    ret.key         #=> "foo"
    ret.value
    ret.cas
  end
end

Parameters:

  • key (String, Symbol)

    Key used to reference the value.

  • delta (Fixnum)

    Integer (up to 64 bits) value to increment

  • options (Hash)

    Options for operation.

Options Hash (options):

  • :create (true, false) — default: false

    If set to true, it will initialize the key with zero value and zero flags (use :initial option to set another initial value). Note: it won’t increment the missing value.

  • :initial (Fixnum) — default: 0

    Integer (up to 64 bits) value for missing key initialization. This option imply :create option is true.

  • :ttl (Fixnum) — default: self.default_ttl

    Expiry time for key. Values larger than 30*24*60*60 seconds (30 days) are interpreted as absolute times (from the epoch). This option ignored for existent keys.

  • :extended (true, false) — default: false

    If set to true, the operation will return tuple [value, cas], otherwise (by default) it returns just value.

Yield Parameters:

  • ret (Result)

    the result of operation in asynchronous mode (valid attributes: error, operation, key, value, cas).

Returns:

  • (Fixnum)

    the actual value of the key.

Raises:

Since:

  • 1.0.0



217
218
219
220
221
# File 'ext/couchbase_ext/arithmetic.c', line 217

VALUE
cb_bucket_incr(int argc, VALUE *argv, VALUE self)
{
    return cb_bucket_arithmetic(+1, argc, argv, self);
}

- (Couchbase::Bucket) initialize_copy

Initialize copy

Initializes copy of the object, used by #dup

Parameters:

Returns:



445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
# File 'ext/couchbase_ext/bucket.c', line 445

VALUE
cb_bucket_init_copy(VALUE copy, VALUE orig)
{
    struct cb_bucket_st *copy_b;
    struct cb_bucket_st *orig_b;

    if (copy == orig)
        return copy;

    if (TYPE(orig) != T_DATA || TYPE(copy) != T_DATA ||
            RDATA(orig)->dfree != (RUBY_DATA_FUNC)cb_bucket_free) {
        rb_raise(rb_eTypeError, "wrong argument type");
    }

    copy_b = DATA_PTR(copy);
    orig_b = DATA_PTR(orig);

    copy_b->self = copy_b->self;
    copy_b->port = orig_b->port;
    copy_b->authority = orig_b->authority;
    copy_b->hostname = orig_b->hostname;
    copy_b->pool = orig_b->pool;
    copy_b->bucket = orig_b->bucket;
    copy_b->username = orig_b->username;
    copy_b->password = orig_b->password;
    copy_b->async = orig_b->async;
    copy_b->quiet = orig_b->quiet;
    copy_b->default_format = orig_b->default_format;
    copy_b->default_flags = orig_b->default_flags;
    copy_b->default_ttl = orig_b->default_ttl;
    copy_b->environment = orig_b->environment;
    copy_b->timeout = orig_b->timeout;
    copy_b->exception = Qnil;
    if (orig_b->on_error_proc != Qnil) {
        copy_b->on_error_proc = rb_funcall(orig_b->on_error_proc, cb_id_dup, 0);
    }
    copy_b->key_prefix_val = orig_b->key_prefix_val;

    do_connect(copy_b);

    return copy;
}

- (String) inspect

Returns a string containing a human-readable representation of the Couchbase::Bucket.

Returns:

  • (String)

Since:

  • 1.0.0



927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
# File 'ext/couchbase_ext/bucket.c', line 927

VALUE
cb_bucket_inspect(VALUE self)
{
    VALUE str;
    struct cb_bucket_st *bucket = DATA_PTR(self);
    char buf[200];

    str = rb_str_buf_new2("#<");
    rb_str_buf_cat2(str, rb_obj_classname(self));
    snprintf(buf, 25, ":%p \"", (void *)self);
    (void)cb_bucket_authority_get(self);
    rb_str_buf_cat2(str, buf);
    rb_str_buf_cat2(str, "http://");
    rb_str_append(str, bucket->authority);
    rb_str_buf_cat2(str, "/pools/");
    rb_str_append(str, bucket->pool);
    rb_str_buf_cat2(str, "/buckets/");
    rb_str_append(str, bucket->bucket);
    rb_str_buf_cat2(str, "/");
    snprintf(buf, 150, "\" default_format=:%s, default_flags=0x%x, quiet=%s, connected=%s, timeout=%u",
            rb_id2name(SYM2ID(bucket->default_format)),
            bucket->default_flags,
            bucket->quiet ? "true" : "false",
            bucket->handle ? "true" : "false",
            bucket->timeout);
    rb_str_buf_cat2(str, buf);
    if (RTEST(bucket->key_prefix_val)) {
        rb_str_buf_cat2(str, ", key_prefix=");
        rb_str_append(str, rb_inspect(bucket->key_prefix_val));
    }
    rb_str_buf_cat2(str, ">");

    return str;
}

- (Couchbase::Bucket::CouchRequest) make_http_request {|res| ... }

Parameters:

  • path (String)
  • options (Hash)

Yield Parameters:

  • res (String, Couchbase::Result)

    the response chunk if the :extended option is false and result object otherwise

Returns:

Since:

  • 1.2.0



412
413
414
415
416
417
418
419
420
421
# File 'ext/couchbase_ext/http.c', line 412

VALUE
cb_bucket_make_http_request(int argc, VALUE *argv, VALUE self)
{
    VALUE args[4]; /* bucket, path, options, block */

    args[0] = self;
    rb_scan_args(argc, argv, "11&", &args[1], &args[2], &args[3]);

    return rb_class_new_instance(4, args, cb_cCouchRequest);
}

- (Hash<String, Array<Result>>, Array<Result>) observe(*keys, options = {}) {|ret| ... }

Observe key state

The state of the keys on all nodes. If the keys argument was String or Symbol, this method will return just array of results (result per each node), otherwise it will return hash map.

Examples:

Observe single key

c.observe("foo")
#=> [#<Couchbase::Result:0x00000001650df0 ...>, ...]

Observe multiple keys

keys = ["foo", "bar"]
stats = c.observe(keys)
stats.size   #=> 2
stats["foo"] #=> [#<Couchbase::Result:0x00000001650df0 ...>, ...]

Parameters:

  • keys (String, Symbol, Array)

    One or several keys to fetch

  • options (Hash)

    Options for operation.

Yield Parameters:

  • ret (Result)

    the result of operation in asynchronous mode (valid attributes: error, status, operation, key, cas, from_master, time_to_persist, time_to_replicate).

Returns:

  • (Hash<String, Array<Result>>, Array<Result>)

    the state of the keys on all nodes. If the keys argument was String or Symbol, this method will return just array of results (result per each node), otherwise it will return hash map.

Since:

  • 1.2.0.dp6



113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
# File 'ext/couchbase_ext/observe.c', line 113

VALUE
cb_bucket_observe(int argc, VALUE *argv, VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    struct cb_context_st *ctx;
    VALUE args, rv, proc, exc;
    lcb_error_t err;
    struct cb_params_st params;

    if (bucket->handle == NULL) {
        rb_raise(cb_eConnectError, "closed connection");
    }
    rb_scan_args(argc, argv, "0*&", &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_observe;
    params.bucket = bucket;
    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");
    }
    ctx->proc = cb_gc_protect(bucket, proc);
    ctx->bucket = bucket;
    rv = rb_hash_new();
    ctx->rv = &rv;
    ctx->exception = Qnil;
    ctx->nqueries = params.cmd.observe.num;
    err = lcb_observe(bucket->handle, (const void *)ctx,
            params.cmd.observe.num, params.cmd.observe.ptr);
    cb_params_destroy(&params);
    exc = cb_check_error(err, "failed to schedule observe request", Qnil);
    if (exc != Qnil) {
        free(ctx);
        rb_exc_raise(exc);
    }
    bucket->nbytes += params.npayload;
    if (bucket->async) {
        cb_maybe_do_loop(bucket);
        return Qnil;
    } else {
        if (ctx->nqueries > 0) {
            /* we have some operations pending */
            lcb_wait(bucket->handle);
        }
        exc = ctx->exception;
        free(ctx);
        if (exc != Qnil) {
            cb_gc_unprotect(bucket, exc);
            rb_exc_raise(exc);
        }
        exc = bucket->exception;
        if (exc != Qnil) {
            bucket->exception = Qnil;
            rb_exc_raise(exc);
        }
        if (params.cmd.observe.num > 1 || params.cmd.observe.array) {
            return rv;  /* return as a hash {key => {}, ...} */
        } else {
            VALUE vv = Qnil;
            rb_hash_foreach(rv, cb_first_value_i, (VALUE)&vv);
            return vv;  /* return first value */
        }
    }
}

- (Fixnum, Hash<String, Fixnum>) observe_and_wait(*keys, &block)

Wait for persistence condition

This operation is useful when some confidence needed regarding the state of the keys. With two parameters :replicated and :persisted it allows to set up the waiting rule.

Parameters:

  • keys (String, Symbol, Array, Hash)

    The list of the keys to observe. Full form is hash with key-cas value pairs, but there are also shortcuts like just Array of keys or single key. CAS value needed to when you need to ensure that the storage persisted exactly the same version of the key you are asking to observe.

  • options (Hash)

    The options for operation

Returns:

  • (Fixnum, Hash<String, Fixnum>)

    will return CAS value just like mutators or pairs key-cas in case of multiple keys.

Raises:

Since:

  • 1.2.0.dp6



286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
# File 'lib/couchbase/bucket.rb', line 286

def observe_and_wait(*keys, &block)
  options = {:timeout => default_observe_timeout}
  options.update(keys.pop) if keys.size > 1 && keys.last.is_a?(Hash)
  verify_observe_options(options)
  if block && !async?
    raise ArgumentError, "synchronous mode doesn't support callbacks"
  end
  if keys.size == 0
    raise ArgumentError, "at least one key is required"
  end
  if keys.size == 1 && keys[0].is_a?(Hash)
    key_cas = keys[0]
  else
    key_cas = keys.flatten.reduce({}) do |h, kk|
      h[kk] = nil   # set CAS to nil
      h
    end
  end
  if async?
    do_observe_and_wait(key_cas, options, &block)
  else
    res = do_observe_and_wait(key_cas, options, &block) while res.nil?
    unless async?
      if keys.size == 1 && (keys[0].is_a?(String) || keys[0].is_a?(Symbol))
        return res.values.first
      else
        return res
      end
    end
  end
end

- (Object) prepend(key, value, options = {})

Note:

This operation is kind of data-aware from server point of view. This mean that the server treats value as binary stream and just perform concatenation, therefore it won’t work with :marshal and :document formats, because of lack of knowledge how to merge values in these formats. See #cas for workaround.

Prepend this object to the existing object

Examples:

Simple prepend example

c.set("foo", "aaa")
c.prepend("foo", "bbb")
c.get("foo")           #=> "bbbaaa"

Using explicit format option

c.default_format       #=> :document
c.set("foo", {"y" => "z"})
c.prepend("foo", '[', :format => :plain)
c.append("foo", ', {"z": "y"}]', :format => :plain)
c.get("foo")           #=> [{"y"=>"z"}, {"z"=>"y"}]

Using optimistic locking. The operation will fail on CAS mismatch

ver = c.set("foo", "aaa")
c.prepend("foo", "bbb", :cas => ver)

Ensure that the key will be persisted at least on the one node

c.prepend("foo", "bar", :observe => {:persisted => 1})

Parameters:

  • key (String, Symbol)

    Key used to reference the value.

  • value (Object)

    Value to be stored

  • options (Hash)

    Options for operation.

Options Hash (options):

  • :cas (Fixnum)

    The CAS value for an object. This value created on the server and is guaranteed to be unique for each value of a given key. This value is used to provide simple optimistic concurrency control when multiple clients or threads try to update an item simultaneously.

  • :format (Symbol) — default: self.default_format

    The representation for storing the value in the bucket. For more info see #default_format.

  • :observe (Hash)

    Apply persistence condition before returning result. When this option specified the library will observe given condition. See #observe_and_wait.

Raises:

Since:

  • 1.0.0



509
510
511
512
513
# File 'ext/couchbase_ext/store.c', line 509

VALUE
cb_bucket_prepend(int argc, VALUE *argv, VALUE self)
{
    return cb_bucket_store(LCB_PREPEND, argc, argv, self);
}

- (Couchbase::Bucket) reconnect(url, options = {}) - (Couchbase::Bucket) reconnect(options = {})

Reconnect the bucket

Reconnect the bucket using initial configuration with optional redefinition.

Overloads:

Since:

  • 1.1.0



510
511
512
513
514
515
516
517
518
519
# File 'ext/couchbase_ext/bucket.c', line 510

VALUE
cb_bucket_reconnect(int argc, VALUE *argv, VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);

    do_scan_connection_options(bucket, argc, argv);
    do_connect(bucket);

    return self;
}

- (Fixnum) replace(key, value, options = {})

Replace the existing object in the database

The CAS value of the object.

Examples:

Replacing missing key

c.replace("foo", "baz")  #=> will raise Couchbase::Error::NotFound: failed to store value (key="foo", error=0x0d)

Ensure that the key will be persisted at least on the one node

c.replace("foo", "bar", :observe => {:persisted => 1})

Parameters:

  • key (String, Symbol)

    Key used to reference the value.

  • value (Object)

    Value to be stored

  • options (Hash)

    Options for operation.

Options Hash (options):

  • :ttl (Fixnum) — default: self.default_ttl

    Expiry time for key. Values larger than 30*24*60*60 seconds (30 days) are interpreted as absolute times (from the epoch).

  • :flags (Fixnum) — default: self.default_flags

    Flags for storage options. Flags are ignored by the server but preserved for use by the client. For more info see #default_flags.

  • :format (Symbol) — default: self.default_format

    The representation for storing the value in the bucket. For more info see #default_format.

  • :cas (Fixnum)

    The CAS value for an object. This value created on the server and is guaranteed to be unique for each value of a given key. This value is used to provide simple optimistic concurrency control when multiple clients or threads try to update an item simultaneously.

  • :observe (Hash)

    Apply persistence condition before returning result. When this option specified the library will observe given condition. See #observe_and_wait.

Returns:

  • (Fixnum)

    The CAS value of the object.

Raises:

Since:

  • 1.0.0



370
371
372
373
374
# File 'ext/couchbase_ext/store.c', line 370

VALUE
cb_bucket_replace(int argc, VALUE *argv, VALUE self)
{
    return cb_bucket_store(LCB_REPLACE, argc, argv, self);
}

- (nil) run {|bucket| ... }

Run the event loop.

Examples:

Use block to run the loop

c = Couchbase.new
c.run do
  c.get("foo") {|ret| puts ret.value}
end

Use lambda to run the loop

c = Couchbase.new
operations = lambda do |c|
  c.get("foo") {|ret| puts ret.value}
end
c.run(&operations)

Use threshold to send out commands automatically

c = Couchbase.connect
sent = 0
c.run(:send_threshold => 8192) do  # 8Kb
  c.set("foo1", "x" * 100) {|r| sent += 1}
  # 128 bytes buffered, sent is 0 now
  c.set("foo2", "x" * 10000) {|r| sent += 1}
  # 10028 bytes added, sent is 2 now
  c.set("foo3", "x" * 100) {|r| sent += 1}
end
# all commands were executed and sent is 3 now

Parameters:

  • options (Hash)

    The options for operation for connection

Yield Parameters:

  • bucket (Bucket)

    the bucket instance

Returns:

  • (nil)

Raises:

Since:

  • 1.0.0



1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
# File 'ext/couchbase_ext/bucket.c', line 1061

VALUE
cb_bucket_run(int argc, VALUE *argv, VALUE self)
{
    VALUE args[3];

    rb_need_block();
    args[0] = self;
    rb_scan_args(argc, argv, "01&", &args[1], &args[2]);
    rb_ensure(do_run, (VALUE)args, ensure_run, (VALUE)args);
    return Qnil;
}

- (true, false) save_design_doc(data)

Update or create design doc with supplied views

Parameters:

  • data (Hash, IO, String)

    The source object containing JSON encoded design document. It must have _id key set, this key should start with _design/.

Returns:

  • (true, false)

Since:

  • 1.2.0



132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
# File 'lib/couchbase/bucket.rb', line 132

def save_design_doc(data)
  attrs = case data
          when String
            MultiJson.load(data)
          when IO
            MultiJson.load(data.read)
          when Hash
            data
          else
            raise ArgumentError, "Document should be Hash, String or IO instance"
          end
  rv = nil
  id = attrs.delete('_id').to_s
  attrs['language'] ||= 'javascript'
  if id !~ /\A_design\//
    rv = Result.new(:operation => :http_request,
                    :key => id,
                    :error => ArgumentError.new("'_id' key must be set and start with '_design/'."))
    yield rv if block_given?
    raise rv.error unless async?
  end
  req = make_http_request(id, :body => MultiJson.dump(attrs),
                          :method => :put, :extended => true)
  req.on_body do |res|
    rv = res
    val = MultiJson.load(res.value)
    if block_given?
      if res.success? && val['error']
        res.error = Error::View.new("save_design_doc", val['error'])
      end
      yield(res)
    end
  end
  req.continue
  unless async?
    rv.success? or raise res.error
  end
end

- (Fixnum) set(key, value, options = {}) {|ret| ... } Also known as: []=

Unconditionally store the object in the Couchbase

The CAS value of the object.

Examples:

Store the key which will be expired in 2 seconds using relative TTL.

c.set("foo", "bar", :ttl => 2)

Store the key which will be expired in 2 seconds using absolute TTL.

c.set("foo", "bar", :ttl => Time.now.to_i + 2)

Force JSON document format for value

c.set("foo", {"bar" => "baz}, :format => :document)

Use hash-like syntax to store the value

c.set["foo"] = {"bar" => "baz}

Use extended hash-like syntax

c["foo", {:flags => 0x1000, :format => :plain}] = "bar"
c["foo", :flags => 0x1000] = "bar"  # for ruby 1.9.x only

Set application specific flags (note that it will be OR-ed with format flags)

c.set("foo", "bar", :flags => 0x1000)

Perform optimistic locking by specifying last known CAS version

c.set("foo", "bar", :cas => 8835713818674332672)

Perform asynchronous call

c.run do
  c.set("foo", "bar") do |ret|
    ret.operation   #=> :set
    ret.success?    #=> true
    ret.key         #=> "foo"
    ret.cas
  end
end

Ensure that the key will be persisted at least on the one node

c.set("foo", "bar", :observe => {:persisted => 1})

Parameters:

  • key (String, Symbol)

    Key used to reference the value.

  • value (Object)

    Value to be stored

  • options (Hash)

    Options for operation.

Options Hash (options):

  • :ttl (Fixnum) — default: self.default_ttl

    Expiry time for key. Values larger than 30*24*60*60 seconds (30 days) are interpreted as absolute times (from the epoch).

  • :flags (Fixnum) — default: self.default_flags

    Flags for storage options. Flags are ignored by the server but preserved for use by the client. For more info see #default_flags.

  • :format (Symbol) — default: self.default_format

    The representation for storing the value in the bucket. For more info see #default_format.

  • :cas (Fixnum)

    The CAS value for an object. This value created on the server and is guaranteed to be unique for each value of a given key. This value is used to provide simple optimistic concurrency control when multiple clients or threads try to update an item simultaneously.

  • :observe (Hash)

    Apply persistence condition before returning result. When this option specified the library will observe given condition. See #observe_and_wait.

Yield Parameters:

  • ret (Result)

    the result of operation in asynchronous mode (valid attributes: error, operation, key).

Returns:

  • (Fixnum)

    The CAS value of the object.

Raises:

Since:

  • 1.0.0



266
267
268
269
270
# File 'ext/couchbase_ext/store.c', line 266

VALUE
cb_bucket_set(int argc, VALUE *argv, VALUE self)
{
    return cb_bucket_store(LCB_SET, argc, argv, self);
}

- (Hash) stats(arg = nil) {|ret| ... }

Request server statistics.

Fetches stats from each node in cluster. Without a key specified the server will respond with a "default" set of statistical information. In asynchronous mode each statistic is returned in separate call where the Result object yielded (+#key+ contains the name of the statistical item and the #value contains the value, the #node will indicate the server address). In synchronous mode it returns the hash of stats keys and node-value pairs as a value.

Where keys are stat keys, values are host-value pairs

Examples:

Found how many items in the bucket

total = 0
c.stats["total_items"].each do |key, value|
  total += value.to_i
end

Found total items number asynchronously

total = 0
c.run do
  c.stats do |ret|
    if ret.key == "total_items"
      total += ret.value.to_i
    end
  end
end

Get memory stats (works on couchbase buckets)

c.stats(:memory)   #=> {"mem_used"=>{...}, ...}

Parameters:

  • arg (String)

    argument to STATS query

Yield Parameters:

  • ret (Result)

    the object with node, key and value attributes.

Returns:

  • (Hash)

    where keys are stat keys, values are host-value pairs

Raises:

Since:

  • 1.0.0



107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
# File 'ext/couchbase_ext/stats.c', line 107

VALUE
cb_bucket_stats(int argc, VALUE *argv, VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    struct cb_context_st *ctx;
    VALUE rv, exc, args, proc;
    lcb_error_t err;
    struct cb_params_st params;

    if (bucket->handle == NULL) {
        rb_raise(cb_eConnectError, "closed connection");
    }
    rb_scan_args(argc, argv, "0*&", &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_stats;
    params.bucket = bucket;
    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.stats.num;
    err = lcb_server_stats(bucket->handle, (const void *)ctx,
            params.cmd.stats.num, params.cmd.stats.ptr);
    exc = cb_check_error(err, "failed to schedule stat request", Qnil);
    cb_params_destroy(&params);
    if (exc != Qnil) {
        free(ctx);
        rb_exc_raise(exc);
    }
    bucket->nbytes += params.npayload;
    if (bucket->async) {
        cb_maybe_do_loop(bucket);
        return Qnil;
    } else {
        if (ctx->nqueries > 0) {
            /* we have some operations pending */
            lcb_wait(bucket->handle);
        }
        exc = ctx->exception;
        free(ctx);
        if (exc != Qnil) {
            cb_gc_unprotect(bucket, exc);
            rb_exc_raise(exc);
        }
        exc = bucket->exception;
        if (exc != Qnil) {
            bucket->exception = Qnil;
            rb_exc_raise(exc);
        }
        return rv;
    }

    return Qnil;
}

- (nil) stop

Stop the event loop.

Examples:

Breakout the event loop when 5th request is completed

c = Couchbase.connect
c.run do
  10.times do |ii|
    c.get("foo") do |ret|
      puts ii
      c.stop if ii == 5
    end
  end
end

Returns:

  • (nil)

Since:

  • 1.2.0



1091
1092
1093
1094
1095
1096
1097
# File 'ext/couchbase_ext/bucket.c', line 1091

VALUE
cb_bucket_stop(VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    lcb_breakout(bucket->handle);
    return Qnil;
}

- (true, false) touch(key, options = {}) {|ret| ... } - (Hash) touch(keys) {|ret| ... }

Update the expiry time of an item

The touch method allow you to update the expiration time on a given key. This can be useful for situations where you want to prevent an item from expiring without resetting the associated value. For example, for a session database you might want to keep the session alive in the database each time the user accesses a web page without explicitly updating the session value, keeping the user’s session active and available.

Overloads:

  • - (true, false) touch(key, options = {}) {|ret| ... }

    true if the operation was successful and false otherwise.

    Examples:

    Touch value using default_ttl

    c.touch("foo")
    

    Touch value using custom TTL (10 seconds)

    c.touch("foo", :ttl => 10)
    

    Parameters:

    • key (String, Symbol)

      Key used to reference the value.

    • options (Hash)

      Options for operation.

    Options Hash (options):

    • :ttl (Fixnum) — default: self.default_ttl

      Expiry time for key. Values larger than 30*24*60*60 seconds (30 days) are interpreted as absolute times (from the epoch).

    • :quiet (true, false) — default: self.quiet

      If set to true, the operation won’t raise error for missing key, it will return nil.

    Yield Parameters:

    • ret (Result)

      the result of operation in asynchronous mode (valid attributes: error, operation, key).

    Returns:

    • (true, false)

      true if the operation was successful and false otherwise.

    Raises:

  • - (Hash) touch(keys) {|ret| ... }

    Mapping keys to result of touch operation (true if the operation was successful and false otherwise)

    Examples:

    Touch several values

    c.touch("foo" => 10, :bar => 20) #=> {"foo" => true, "bar" => true}
    

    Touch several values in async mode

    c.run do
      c.touch("foo" => 10, :bar => 20) do |ret|
         ret.operation   #=> :touch
         ret.success?    #=> true
         ret.key         #=> "foo" and "bar" in separate calls
      end
    end
    

    Touch single value

    c.touch("foo" => 10)             #=> true
    

    Parameters:

    • keys (Hash)

      The Hash where keys represent the keys in the database, values — the expiry times for corresponding key. See description of :ttl argument above for more information about TTL values.

    Yield Parameters:

    • ret (Result)

      the result of operation for each key in asynchronous mode (valid attributes: error, operation, key).

    Returns:

    • (Hash)

      Mapping keys to result of touch operation (true if the operation was successful and false otherwise)

Since:

  • 1.0.0



124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
# File 'ext/couchbase_ext/touch.c', line 124

VALUE
cb_bucket_touch(int argc, VALUE *argv, VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    struct cb_context_st *ctx;
    VALUE args, rv, proc, exc;
    lcb_error_t err;
    struct cb_params_st params;

    if (bucket->handle == NULL) {
        rb_raise(cb_eConnectError, "closed connection");
    }
    rb_scan_args(argc, argv, "0*&", &args, &proc);
    if (!bucket->async && proc != Qnil) {
        rb_raise(rb_eArgError, "synchronous mode doesn't support callbacks");
    }
    rb_funcall(args, cb_id_flatten_bang, 0);
    memset(&params, 0, sizeof(struct cb_params_st));
    params.type = cb_cmd_touch;
    params.bucket = bucket;
    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");
    }
    ctx->proc = cb_gc_protect(bucket, proc);
    ctx->bucket = bucket;
    rv = rb_hash_new();
    ctx->rv = &rv;
    ctx->exception = Qnil;
    ctx->quiet = params.cmd.touch.quiet;
    ctx->nqueries = params.cmd.touch.num;
    err = lcb_touch(bucket->handle, (const void *)ctx,
            params.cmd.touch.num, params.cmd.touch.ptr);
    cb_params_destroy(&params);
    exc = cb_check_error(err, "failed to schedule touch request", Qnil);
    if (exc != Qnil) {
        free(ctx);
        rb_exc_raise(exc);
    }
    bucket->nbytes += params.npayload;
    if (bucket->async) {
        cb_maybe_do_loop(bucket);
        return Qnil;
    } else {
        if (ctx->nqueries > 0) {
            /* we have some operations pending */
            lcb_wait(bucket->handle);
        }
        exc = ctx->exception;
        free(ctx);
        if (exc != Qnil) {
            rb_exc_raise(cb_gc_unprotect(bucket, exc));
        }
        exc = bucket->exception;
        if (exc != Qnil) {
            bucket->exception = Qnil;
            rb_exc_raise(exc);
        }
        if (params.cmd.touch.num > 1) {
            return rv;  /* return as a hash {key => true, ...} */
        } else {
            VALUE vv = Qnil;
            rb_hash_foreach(rv, cb_first_value_i, (VALUE)&vv);
            return vv;
        }
    }
}

- (true, false) unlock(key, options = {}) - (Hash) unlock(keys) {|ret| ... }

Unlock key

The unlock method allow you to unlock key once locked by #get with :lock option.

Overloads:

  • - (true, false) unlock(key, options = {})

    true if the operation was successful and false otherwise.

    Examples:

    Unlock the single key

    val, _, cas = c.get("foo", :lock => true, :extended => true)
    c.unlock("foo", :cas => cas)
    

    Parameters:

    • key (String, Symbol)

      Key used to reference the value.

    • options (Hash)

      Options for operation.

    Options Hash (options):

    • :cas (Fixnum)

      The CAS value must match the current one from the storage.

    • :quiet (true, false) — default: self.quiet

      If set to true, the operation won’t raise error for missing key, it will return nil.

    Returns:

    • (true, false)

      true if the operation was successful and false otherwise.

    Raises:

  • - (Hash) unlock(keys) {|ret| ... }

    Mapping keys to result of unlock operation (true if the operation was successful and false otherwise)

    Examples:

    Unlock several keys

    c.unlock("foo" => cas1, :bar => cas2) #=> {"foo" => true, "bar" => true}
    

    Unlock several values in async mode

    c.run do
      c.unlock("foo" => 10, :bar => 20) do |ret|
         ret.operation   #=> :unlock
         ret.success?    #=> true
         ret.key         #=> "foo" and "bar" in separate calls
      end
    end
    

    Parameters:

    • keys (Hash)

      The Hash where keys represent the keys in the database, values — the CAS for corresponding key.

    Yield Parameters:

    • ret (Result)

      the result of operation for each key in asynchronous mode (valid attributes: error, operation, key).

    Returns:

    • (Hash)

      Mapping keys to result of unlock operation (true if the operation was successful and false otherwise)

Since:

  • 1.2.0



114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
# File 'ext/couchbase_ext/unlock.c', line 114

VALUE
cb_bucket_unlock(int argc, VALUE *argv, VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    struct cb_context_st *ctx;
    VALUE args, rv, proc, exc;
    lcb_error_t err;
    struct cb_params_st params;

    if (bucket->handle == NULL) {
        rb_raise(cb_eConnectError, "closed connection");
    }
    rb_scan_args(argc, argv, "0*&", &args, &proc);
    if (!bucket->async && proc != Qnil) {
        rb_raise(rb_eArgError, "synchronous mode doesn't support callbacks");
    }
    rb_funcall(args, cb_id_flatten_bang, 0);
    memset(&params, 0, sizeof(struct cb_params_st));
    params.type = cb_cmd_unlock;
    params.bucket = bucket;
    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");
    }
    ctx->proc = cb_gc_protect(bucket, proc);
    ctx->bucket = bucket;
    rv = rb_hash_new();
    ctx->rv = &rv;
    ctx->exception = Qnil;
    ctx->quiet = params.cmd.unlock.quiet;
    ctx->nqueries = params.cmd.unlock.num;
    err = lcb_unlock(bucket->handle, (const void *)ctx,
            params.cmd.unlock.num, params.cmd.unlock.ptr);
    cb_params_destroy(&params);
    exc = cb_check_error(err, "failed to schedule unlock request", Qnil);
    if (exc != Qnil) {
        free(ctx);
        rb_exc_raise(exc);
    }
    bucket->nbytes += params.npayload;
    if (bucket->async) {
        cb_maybe_do_loop(bucket);
        return Qnil;
    } else {
        if (ctx->nqueries > 0) {
            /* we have some operations pending */
            lcb_wait(bucket->handle);
        }
        exc = ctx->exception;
        free(ctx);
        if (exc != Qnil) {
            rb_exc_raise(cb_gc_unprotect(bucket, exc));
        }
        exc = bucket->exception;
        if (exc != Qnil) {
            bucket->exception = Qnil;
            rb_exc_raise(exc);
        }
        if (params.cmd.unlock.num > 1) {
            return rv;  /* return as a hash {key => true, ...} */
        } else {
            VALUE vv = Qnil;
            rb_hash_foreach(rv, cb_first_value_i, (VALUE)&vv);
            return vv;
        }
    }
}

- (Hash) version {|ret| ... }

Returns versions of the server for each node in the cluster

Node-version pairs

Examples:

Synchronous version request

c.version            #=> will render version

Asynchronous version request

c.run do
  c.version do |ret|
    ret.operation    #=> :version
    ret.success?     #=> true
    ret.node         #=> "localhost:11211"
    ret.value        #=> will render version
  end
end

Yield Parameters:

  • ret (Result)

    the object with error, node, operation and value attributes.

Returns:

  • (Hash)

    node-version pairs

Raises:

Since:

  • 1.1.0



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
# File 'ext/couchbase_ext/version.c', line 88

VALUE
cb_bucket_version(int argc, VALUE *argv, VALUE self)
{
    struct cb_bucket_st *bucket = DATA_PTR(self);
    struct cb_context_st *ctx;
    VALUE rv, exc, args, proc;
    lcb_error_t err;
    struct cb_params_st params;

    if (bucket->handle == NULL) {
        rb_raise(cb_eConnectError, "closed connection");
    }
    rb_scan_args(argc, argv, "0*&", &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_version;
    params.bucket = bucket;
    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->exception = Qnil;
    ctx->proc = cb_gc_protect(bucket, proc);
    ctx->nqueries = params.cmd.version.num;
    err = lcb_server_versions(bucket->handle, (const void *)ctx,
            params.cmd.version.num, params.cmd.version.ptr);
    exc = cb_check_error(err, "failed to schedule version request", Qnil);
    cb_params_destroy(&params);
    if (exc != Qnil) {
        free(ctx);
        rb_exc_raise(exc);
    }
    bucket->nbytes += params.npayload;
    if (bucket->async) {
        cb_maybe_do_loop(bucket);
        return Qnil;
    } else {
        if (ctx->nqueries > 0) {
            /* we have some operations pending */
            lcb_wait(bucket->handle);
        }
        exc = ctx->exception;
        free(ctx);
        if (exc != Qnil) {
            cb_gc_unprotect(bucket, exc);
            rb_exc_raise(exc);
        }
        exc = bucket->exception;
        if (exc != Qnil) {
            bucket->exception = Qnil;
            rb_exc_raise(exc);
        }
        return rv;
    }
}