Class: Couchbase::Bucket

Inherits:

Object

Object
Couchbase::Bucket

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:

1.0.0

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)

- (String) authority readonly
The authority ("hostname:port") of the current node.
- (String) bucket (also: #name) readonly
The bucket name of the current connection.
- (Fixnum, true) default_arithmetic_init
The initial value for arithmetic operations #incr and #decr.
- (Fixnum) default_flags
Default flags for new values.
- (Symbol) default_format
Default format for new values.
- (Fixnum) default_observe_timeout
The default timeout value for #observe_and_wait operation in microseconds.
- (Symbol) environment readonly
The environment of the connection (+:development+ or :production).
- (String) hostname readonly
The hostname of the current node.
- (String) key_prefix
The library will prepend key_prefix to each key to provide simple namespacing.
- (Fixnum) num_replicas readonly
The numbers of the replicas for each node in the cluster.
- (Proc) on_error {|op, key, exc| ... }
Error callback for asynchronous mode.
- (String) password readonly
The password used to connect to the cluster.
- (String) pool readonly
The pool name of the current connection.
- (Fixnum) port readonly
The port of the current node.
- (true, false) quiet (also: #quiet?)
Flag specifying behaviour for operations on missing keys.
- (Fixnum) timeout
The timeout for the operations in microseconds.
- (String) url readonly
The config url for this connection.
- (String) username readonly
The user name used to connect to the cluster.

Instance Method Summary (collapse)

- (Fixnum) add(key, value, options = {}) {|ret| ... }
Add the item to the database, but fail if the object exists already.
- (Fixnum) append(key, value, options = {})
Append this object to the existing object.
- (true, ...) async?
Check whether the connection asynchronous.
- (Fixnum) cas(key, options = {}) {|value| ... } (also: #compare_and_swap)
Compare and swap value.
- (true, ...) connected?
Check whether the instance connected to the cluster.
- (Couchbase::Timer) create_periodic_timer(interval, &block)
Create and register periodic timer.
- (Couchbase::Timer) create_timer(interval, &block)
Create and register one-shot timer.
- (Fixnum) decr(key, delta = 1, options = {}) {|ret| ... } (also: #decrement)
Decrement the value of an existing numeric key.
- (true, ...) delete(key, options = {})
Delete the specified key.
- (true, false) delete_design_doc(id, rev = nil)
Delete design doc with given id and revision.
- (Hash) design_docs
Fetch design docs stored in current bucket.
- (true) disconnect
Close the connection to the cluster.
- (true) flush {|ret| ... }
Delete contents of the bucket.
- (Object) get (also: #[])
Obtain an object stored in Couchbase by given key.
- (Fixnum) incr(key, delta = 1, options = {}) {|ret| ... } (also: #increment)
Increment the value of an existing numeric key.
- (Bucket) initialize constructor
Initialize new Bucket.
- (Couchbase::Bucket) initialize_copy
Initialize copy.
- (String) inspect
Returns a string containing a human-readable representation of the Bucket.
- (Couchbase::Bucket::CouchRequest) make_http_request {|res| ... }
- (Hash<String, Array<Result>>, Array<Result>) observe(*keys, options = {}) {|ret| ... }
Observe key state.
- (Fixnum, Hash<String, Fixnum>) observe_and_wait(*keys, &block)
Wait for persistence condition.
- (Object) prepend(key, value, options = {})
Prepend this object to the existing object.
- (Object) reconnect
Reconnect the bucket.
- (Fixnum) replace(key, value, options = {})
Replace the existing object in the database.
- (nil) run {|bucket| ... }
Run the event loop.
- (true, false) save_design_doc(data)
Update or create design doc with supplied views.
- (Fixnum) set(key, value, options = {}) {|ret| ... } (also: #[]=)
Unconditionally store the object in the Couchbase.
- (Hash) stats(arg = nil) {|ret| ... }
Request server statistics.
- (nil) stop
Stop the event loop.
- (Object) touch
Update the expiry time of an item.
- (Object) unlock
Unlock key.
- (Hash) version {|ret| ... }
Returns versions of the server for each node in the cluster.

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:

(Couchbase::Error::BucketNotFound) —
if there no such bucket to connect
(Couchbase::Error::Connect) —
if the socket wasn’t accessible (doesn’t accept connections or doesn’t respond in time)

Since:

1.0.0

# 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:

#url

Since:

1.0.0

# 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:

#url

Since:

1.0.0

# 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

# 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

# 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:

http://couchbase.com/docs/couchbase-manual-2.0/couchbase-views-datastore.html

Since:

1.0.0

# 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

# 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

# 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:

#url

Since:

1.0.0

# 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

# 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

# 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

# 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

# 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:

#url

Since:

1.0.0

# 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:

#url

Since:

1.0.0

# 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

# 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

# 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

# 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:

#url

Since:

1.0.0

# 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:

(Couchbase::Error::Connect) —
if connection closed (see #reconnect)
(Couchbase::Error::KeyExists) —
if the key already exists on the server
(Couchbase::Error::ValueFormat) —
if the value cannot be serialized with chosen encoder, e.g. if you try to store the Hash in :plain mode.
(ArgumentError) —
when passing the block in synchronous mode
(Couchbase::Error::Timeout) —
if timeout interval for observe exceeds

Since:

1.0.0

# 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:

(Couchbase::Error::Connect) —
if connection closed (see #reconnect)
(Couchbase::Error::KeyExists) —
on CAS mismatch
(Couchbase::Error::NotStored) —
if the key doesn’t exist
(ArgumentError) —
when passing the block in synchronous mode
(Couchbase::Error::Timeout) —
if timeout interval for observe exceeds

Since:

1.0.0

# 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:

#run

Since:

1.0.0

# 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:

http://couchbase.com/docs/memcached-api/memcached-api-protocol-text_cas.html

Since:

1.0.0

# 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

# 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:

(Couchbase::Timer)



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:

(Couchbase::Timer)



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:

(Couchbase::Error::NotFound) —
if key is missing and :create option isn’t true.
(Couchbase::Error::DeltaBadval) —
if the key contains non-numeric value
(Couchbase::Error::Connect) —
if connection closed (see #reconnect)
(ArgumentError) —
when passing the block in synchronous mode

Since:

1.0.0

# 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:

(Couchbase::Error::Connect) —
if connection closed (see #reconnect)
(ArgumentError) —
when passing the block in synchronous mode
(Couchbase::Error::KeyExists) —
on CAS mismatch
(Couchbase::Error::NotFound) —
if key is missing in verbose mode

Since:

1.0.0

# 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

# 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

# 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:

(Couchbase::Error::Connect) —
if connection closed (see #reconnect)

Since:

1.1.0

# 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:

(Couchbase::Error::Protocol) —
in case of an error is encountered. Check Error::Base#status for detailed code.

See Also:

http://www.couchbase.com/docs/couchbase-manual-2.0/restapi-flushing-bucket.html

Since:

1.2.0.beta

# 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:
- (Couchbase::Error::NotFound) —
  if the key is missing in the bucket.
- (Couchbase::Error::Connect) —
  if connection closed (see #reconnect)
- (ArgumentError) —
  when passing the block in synchronous mode
- (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 => value} or {key => [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:

http://couchbase.com/docs/couchbase-manual-2.0/couchbase-architecture-apis-memcached-protocol-additions.html#couchbase-architecture-apis-memcached-protocol-additions-getl

Since:

1.0.0

# 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:

(Couchbase::Error::NotFound) —
if key is missing and :create option isn’t true.
(Couchbase::Error::DeltaBadval) —
if the key contains non-numeric value
(Couchbase::Error::Connect) —
if connection closed (see #reconnect)
(ArgumentError) —
when passing the block in synchronous mode

Since:

1.0.0

# 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:

orig (Couchbase::Bucket) —
the source for copy

Returns:

(Couchbase::Bucket)

# 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

# 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:

(Couchbase::Bucket::CouchRequest)

Since:

1.2.0

# 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

# 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:

(Couchbase::Error::Timeout) —
if the given time is up

Since:

1.2.0.dp6

# 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:

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:

(Couchbase::Error::Connect) —
if connection closed (see #reconnect)
(Couchbase::Error::KeyExists) —
on CAS mismatch
(Couchbase::Error::NotStored) —
if the key doesn’t exist
(ArgumentError) —
when passing the block in synchronous mode
(Couchbase::Error::Timeout) —
if timeout interval for observe exceeds

Since:

1.0.0

# 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:

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

see Bucket#initialize(url, options)
Returns:
- (Couchbase::Bucket)
- (Couchbase::Bucket) reconnect(options = {})

see Bucket#initialize(options)
Examples:

reconnect with current parameters
```
c.reconnect
```
reconnect the instance to another bucket
```
c.reconnect(:bucket => 'new')
```
Returns:
- (Couchbase::Bucket)

Since:

1.1.0

# 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:

(Couchbase::Error::Connect) —
if connection closed (see #reconnect)
(Couchbase::Error::NotFound) —
if the key doesn’t exists
(Couchbase::Error::KeyExists) —
on CAS mismatch
(ArgumentError) —
when passing the block in synchronous mode
(Couchbase::Error::Timeout) —
if timeout interval for observe exceeds

Since:

1.0.0

# 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:

(Couchbase::Error::Connect) —
if connection closed (see #reconnect)

Since:

1.0.0

# 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

# 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:

(Couchbase::Error::Connect) —
if connection closed (see #reconnect).
(Couchbase::Error::KeyExists) —
if the key already exists on the server.
(Couchbase::Error::ValueFormat) —
if the value cannot be serialized with chosen encoder, e.g. if you try to store the Hash in :plain mode.
(ArgumentError) —
when passing the block in synchronous mode
(Couchbase::Error::Timeout) —
if timeout interval for observe exceeds

Since:

1.0.0

# 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:

(Couchbase::Error::Connect) —
if connection closed (see #reconnect)
(ArgumentError) —
when passing the block in synchronous mode

Since:

1.0.0

# 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

# 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:
- (Couchbase::Error::Connect) —
  if connection closed (see #reconnect)
- (ArgumentError) —
  when passing the block in synchronous mode
- (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

# 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:
- (Couchbase::Error::Connect) —
  if connection closed (see #reconnect)
- (ArgumentError) —
  when passing the block in synchronous mode
- (Couchbase::Error::NotFound) —
  if key(s) not found in the storage
- (Couchbase::Error::TemporaryFail) —
  if either the key wasn’t locked or given CAS value doesn’t match to actual in the storage
- (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

# 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:

(Couchbase::Error::Connect) —
if connection closed (see #reconnect)
(ArgumentError) —
when passing the block in synchronous mode

Since:

1.1.0

# 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;
    }
}

Class: Couchbase::Bucket

Overview

Defined Under Namespace

Constant Summary

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

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

Instance Attribute Details

- (String) authority (readonly)

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

- (Fixnum, true) default_arithmetic_init

- (Fixnum) default_flags

- (Symbol) default_format

- (Fixnum) default_observe_timeout

- (Symbol) environment (readonly)

- (String) hostname (readonly)

- (String) key_prefix

- (Fixnum) num_replicas (readonly)

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

- (String) password (readonly)

- (String) pool (readonly)

- (Fixnum) port (readonly)

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

- (Fixnum) timeout

- (String) url (readonly)

- (String) username (readonly)

Instance Method Details

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

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

- (true, ...) async?

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

- (true, ...) connected?

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

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

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

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

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

- (Hash) design_docs

- (true) disconnect

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

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

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

- (Couchbase::Bucket) initialize_copy

- (String) inspect

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

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

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

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

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

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

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

- (true, false) save_design_doc(data)

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

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

- (nil) stop

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

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

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

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

- (`String`) authority (readonly)

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

- (`Fixnum`, `true`) default_arithmetic_init

- (`Fixnum`) default_flags

- (`Symbol`) default_format

- (`Fixnum`) default_observe_timeout

- (`Symbol`) environment (readonly)

- (`String`) hostname (readonly)

- (`String`) key_prefix

- (`Fixnum`) num_replicas (readonly)

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

- (`String`) password (readonly)

- (`String`) pool (readonly)

- (`Fixnum`) port (readonly)

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

- (`Fixnum`) timeout

- (`String`) url (readonly)

- (`String`) username (readonly)

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

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

- (`true`, ...) async?

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

- (`true`, ...) connected?

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

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

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

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

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

- (`Hash`) design_docs

- (`true`) disconnect

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

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

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

- (`Couchbase::Bucket`) initialize_copy

- (`String`) inspect

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

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

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

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

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

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

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

- (`true`, `false`) save_design_doc(data)

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

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

- (`nil`) stop

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

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

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