Module: Couchbase::Memcached

Included in:
Bucket
Defined in:
lib/couchbase/memcached.rb

Overview

This module is included in the Couchbase::Connection and provides routines for Memcached API

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#default_flags ⇒ Object (readonly)

Returns the value of attribute default_flags.



27
28
29
 
# File 'lib/couchbase/memcached.rb', line 27

def default_flags
  @default_flags
end

#default_format ⇒ Object (readonly)

Returns the value of attribute default_format.



27
28
29
 
# File 'lib/couchbase/memcached.rb', line 27

def default_format
  @default_format
end

#default_ttl ⇒ Object (readonly)

Returns the value of attribute default_ttl.



27
28
29
 
# File 'lib/couchbase/memcached.rb', line 27

def default_ttl
  @default_ttl
end

#memcached ⇒ Object (readonly)

Returns the value of attribute memcached.



27
28
29
 
# File 'lib/couchbase/memcached.rb', line 27

def memcached
  @memcached
end

Instance Method Details

#[](keys) ⇒ Object

Shortcut to #get operation. Gets a key’s value from the server with default options. (@see #get method for additional info)

Parameters:

  • keys (Array, String) —

    list of String keys or single key

Raises:

  • (Memcached::NotFound) —

    if the key does not exist on the server.



147
148
149
 
# File 'lib/couchbase/memcached.rb', line 147

def [](keys)
  decode(@memcached.get(keys, @default_format == :marshal), @default_format)
end

#[]=(key, value) ⇒ Object

Shortcut to #set operation. Sets key to given value using default options.

Parameters:

  • key (String)
  • value (Object) 


184
185
186
187
 
# File 'lib/couchbase/memcached.rb', line 184

def []=(key, value)
  @memcached.set(key, encode(value, @default_format),
                 @default_ttl, @default_format == :marshal, @default_flags)
end

#add(key, value, options = {}) ⇒ Object

Add a key/value pair.

Parameters:

  • key (String)
  • value (Object)
  • options (Hash) (defaults to: {}) —

    the options for operation

Options Hash (options):

  • :ttl (String) — 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

Raises:

  • (Memcached::NotStored) —

    if the key already exists on the server.



245
246
247
248
249
250
 
# File 'lib/couchbase/memcached.rb', line 245

def add(key, value, options = {})
  ttl = options[:ttl] || @default_ttl
  format = options[:format] || @default_format
  flags = options[:flags] || @default_flags
  @memcached.add(key, encode(value, format), ttl, format == :marshal, flags)
end

#append(key, value) ⇒ Object

Appends a string to a key’s value. Make sense for :plain format, because server doesn’t make assumptions about value structure here.

Parameters:

  • key (String)
  • value (Object)

Raises:

  • (Memcached::NotFound) —

    if the key doesn’t exists on the server.



281
282
283
 
# File 'lib/couchbase/memcached.rb', line 281

def append(key, value)
  @memcached.append(key, value)
end

#cas(key, options = {}) {|value| ... } ⇒ Object Also known as: compare_and_swap

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 Memcached::NotStored. CAS stands for “compare and swap”, and avoids the need for manual key mutexing. Read more info here:

http://docs.couchbase.org/memcached-api/memcached-api-protocol-text.html#memcached-api-protocol-text_cas

Examples:

Implement append to JSON encoded value


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

Parameters:

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

    the options for operation

Options Hash (options):

  • :ttl (String) — 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) —

    old value.

Yield Returns:

  • (Object) —

    new value.

Raises:

  • (Memcached::ClientError) —

    if CAS doesn’t enabled for current connection. (:support_cas is true by default)

  • (Memcached::NotStored) —

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



222
223
224
225
226
227
228
229
230
 
# File 'lib/couchbase/memcached.rb', line 222

def cas(key, options = {}, &block)
  ttl = options[:ttl] || @default_ttl
  format = options[:format] || @default_format
  flags = options[:flags] || @default_flags
  @memcached.cas(key, ttl, format == :marshal, flags) do |value|
    value = decode(value, format)
    encode(block.call(value), format)
  end
end

#clone ⇒ Object Also known as: dup

Safely copy this instance.

clone is useful for threading, since each thread must have its own unshared object.



335
336
337
338
339
 
# File 'lib/couchbase/memcached.rb', line 335

def clone
  double = super
  double.instance_variable_set("@memcached", @memcached.clone)
  double
end

#decrement(key, offset = 1) ⇒ Object Also known as: decr

Decrement a key’s value. The key must be initialized to a plain integer first via #set, #add, or #replace with :format set to :plain.

Parameters:

  • key (String)
  • offset (Fixnum) (defaults to: 1) —

    the value to substract



327
328
329
 
# File 'lib/couchbase/memcached.rb', line 327

def decrement(key, offset = 1)
  @memcached.decrement(key, offset)
end

#delete(key) ⇒ Object

Deletes a key/value pair from the server.

Parameters:

  • key (String)

Raises:

  • (Memcached::NotFound) —

    if the key doesn’t exists on the server.



304
305
306
 
# File 'lib/couchbase/memcached.rb', line 304

def delete(key)
  @memcached.delete(key)
end

#flush ⇒ Object

Flushes all key/value pairs from all the servers.



99
100
101
 
# File 'lib/couchbase/memcached.rb', line 99

def flush
  @memcached.flush
end

#get(key, options = {}) ⇒ Object #get(*keys, options = {}) ⇒ Hash

Gets a key’s value from the server. It will use multiget behaviour if you pass Array of keys, which is much faster than normal mode.

Overloads:

  • #get(key, options = {}) ⇒ Object

    Get single key.

    Parameters:

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

      the options for operation

    Options Hash (options):

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

      format of the value

    Returns:

    • (Object) —

      the value is associated with the key

    Raises:

    • (Memcached::NotFound) —

      if the key does not exist on the server.

  • #get(*keys, options = {}) ⇒ Hash

    Get multiple keys aka multiget (mget).

    Parameters:

    • keys (Array) —

      the list of keys

    • options (Hash) (defaults to: {}) —

      the options for operation

    Options Hash (options):

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

      format of the value

    Returns:

    • (Hash) —

      result map, where keys are keys which were requested and values are the values from the storage. Result will contain only existing keys and in this case no exception will be raised.

Raises:

  • (ArgumentError) 


125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/couchbase/memcached.rb', line 125

def get(*args)
  options = args.last.is_a?(Hash) ? args.pop : {}
  raise ArgumentError, "You must provide at least one key" if args.empty?
  keys = args.length == 1 ? args.pop : args
  format = options[:format] || @default_format
  rv = @memcached.get(keys, format == :marshal)
  if keys.is_a?(Array)
    rv.keys.each do |key|
      rv[key] = decode(rv[key], format)
    end
    rv
  else
    decode(rv, format)
  end
end

#increment(key, offset = 1) ⇒ Object Also known as: incr

Increment a key’s value. The key must be initialized to a plain integer first via #set, #add, or #replace with :format set to :plain.

Parameters:

  • key (String)
  • offset (Fixnum) (defaults to: 1) —

    the value to add



315
316
317
 
# File 'lib/couchbase/memcached.rb', line 315

def increment(key, offset = 1)
  @memcached.increment(key, offset)
end

#initialize(pool_uri, options = {}) ⇒ Object

Initializes Memcached API. It builds a server list using moxi ports.

Parameters:

  • options (Hash) (defaults to: {}) —

    The options for module

Options Hash (options):

  • :format (Symbol) —

    format of the values. It can be on of the [:plain, :document, :marshal]. You can choose :plain if you no need any conversions to be applied to your data, but your data should be passed as String. Choose :document (default) format when you’ll store hashes and plan to execute CouchDB views with map/reduce operations on them. And finally use :marshal format if you’d like to transparently serialize almost any ruby object with standard Marshal.dump and Marhal.load methods.



41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/couchbase/memcached.rb', line 41

def initialize(pool_uri, options = {})
  @default_format = options[:format] || :document
  @default_flags = ::Memcached::FLAGS
  @options = {
    :binary_protocol => true,
    :support_cas => true,
    :default_ttl => 0
  }.merge(options || {})
  @options[:experimental_features] = true
  if @credentials
    @options[:credentials] = [@credentials[:username], @credentials[:password]]
  end
  super
end

#options ⇒ Hash

Returns effective options from Memcached instance

Returns:

  • (Hash) 


59
60
61
 
# File 'lib/couchbase/memcached.rb', line 59

def options
  @memcached.options
end

#prefix_key ⇒ String Also known as: namespace

Return the current prefix key.

Returns:

  • (String) 


81
82
83
 
# File 'lib/couchbase/memcached.rb', line 81

def prefix_key
  @memcached.prefix_key
end

#prefix_key=(prefix) ⇒ Object Also known as: namespace=

Set the prefix key.

Parameters:

  • prefix (String) —

    the string to prepend before each key.



73
74
75
 
# File 'lib/couchbase/memcached.rb', line 73

def prefix_key=(prefix)
  @memcached.prefix_key(prefix)
end

#prepend(key, value) ⇒ Object

Prepends a string to a key’s value. Make sense for :plain format, because server doesn’t make assumptions about value structure here.

Parameters:

  • key (String)
  • value (Object)

Raises:

  • (Memcached::NotFound) —

    if the key doesn’t exists on the server.



295
296
297
 
# File 'lib/couchbase/memcached.rb', line 295

def prepend(key, value)
  @memcached.prepend(key, value)
end

#replace(key, value, options = {}) ⇒ Object

Replace a key/value pair.

Parameters:

  • key (String)
  • value (Object)
  • options (Hash) (defaults to: {}) —

    the options for operation

Options Hash (options):

  • :ttl (String) — 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

Raises:

  • (Memcached::NotFound) —

    if the key doesn’t exists on the server.



265
266
267
268
269
270
 
# File 'lib/couchbase/memcached.rb', line 265

def replace(key, value, options = {})
  ttl = options[:ttl] || @default_ttl
  format = options[:format] || @default_format
  flags = options[:flags] || @default_flags
  @memcached.replace(key, encode(value, format), ttl, format == :marshal, flags)
end

#servers ⇒ Array

Return the array of server strings used to configure this instance.

Returns:

  • (Array) 


66
67
68
 
# File 'lib/couchbase/memcached.rb', line 66

def servers
  @memcached.servers
end

#set(key, value, options = {}) ⇒ Object

Set a key/value pair. Overwrites any existing value on the server.

Parameters:

  • key (String)
  • value (Object)
  • options (Hash) (defaults to: {}) —

    the options for operation

Options Hash (options):

  • :ttl (String) — 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



171
172
173
174
175
176
 
# File 'lib/couchbase/memcached.rb', line 171

def set(key, value, options = {})
  ttl = options[:ttl] || @default_ttl
  format = options[:format] || @default_format
  flags = options[:flags] || @default_flags
  @memcached.set(key, encode(value, format), ttl, format == :marshal, flags)
end

#stats(key = nil) ⇒ Hash

Return a hash of statistics responses from the set of servers. Each value is an array with one entry for each server, in the same order the servers were defined.

Parameters:

  • key (String) (defaults to: nil) —

    The name of the statistical item. When key is nil, the server will return all set of statistics information.

Returns:

  • (Hash) 


94
95
96
 
# File 'lib/couchbase/memcached.rb', line 94

def stats(key = nil)
  @memcached.stats(key)
end

#touch(key, ttl = @default_ttl) ⇒ Object

Set new expiration time for existing item. The ttl parameter will use #default_ttl value if it is nil.

Parameters:

  • key (String)
  • ttl (Fixnum) (defaults to: @default_ttl) 


157
158
159
 
# File 'lib/couchbase/memcached.rb', line 157

def touch(key, ttl = @default_ttl)
  @memcached.touch(key, ttl)
end