Class: MemCache

Class | MemCache
In: | lib/active_support/vendor/memcache-client-1.5.1/memcache.rb
Parent: | Object

A Ruby client library for memcached.

This is intended to provide access to basic memcached functionality. It does not attempt to be complete implementation of the entire API, but it is approaching a complete implementation.

### Methods

[] []= active? add cache_decr cache_get cache_get_multi cache_incr decr delete flush_all get get_multi get_server_for_key handle_error hash_for incr inspect make_cache_key new raise_on_error_response! readonly? request_setup reset servers= set stats

### Classes and Modules

Class MemCache::MemCacheError
Class MemCache::Server

### Constants

VERSION | = | '1.5.0' |  | The version of MemCache you are using.
DEFAULT_OPTIONS | = | { :namespace => nil, :readonly => false, :multithread => false, } |  | Default options for the cache object.
DEFAULT_PORT | = | 11211 |  | Default memcached port.
DEFAULT_WEIGHT | = | 1 |  | Default memcached server weight.

### Attributes

multithread | [R] | The multithread setting for this instance
namespace | [R] | The namespace for this instance
request_timeout | [RW] | The amount of time to wait for a response from a memcached server. If a response is not completed within this time, the connection to the server will be closed and an error will be raised.
servers | [R] | The servers this client talks to. Play at your own peril.

### Public Class methods

new(*args)

Accepts a list of `servers` and a list of `opts`. `servers` may be omitted. See +servers=+ for acceptable server list arguments.

Valid options for `opts` are:

      [:namespace]   Prepends this value to all keys added or retrieved.
      [:readonly]    Raises an exception on cache writes when true.
      [:multithread] Wraps cache access in a Mutex for thread safety.

Other options are ignored.

### Public Instance methods

[](key, raw = false)

Alias for get

[]=(key, value)

Shortcut to save a value in the cache. This method does not set an expiration on the entry. Use set to specify an explicit expiry.

active?()

Returns whether there is at least one active server for the object.

add(key, value, expiry = 0, raw = false)

Add `key` to the cache with value `value` that expires in `expiry` seconds, but only if `key` does not already exist in the cache. If `raw` is true, `value` will not be Marshalled.

Readers should call this method in the event of a cache miss, not MemCache#set or MemCache#[]=.

decr(key, amount = 1)

Decrements the value for `key` by `amount` and returns the new value. `key` must already exist. If `key` is not an integer, it is assumed to be

1. `key` can not be decremented below 0.

delete(key, expiry = 0)

Removes `key` from the cache in `expiry` seconds.

flush_all()

Flush the cache from all memcache servers.

get(key, raw = false)

Retrieves `key` from memcache. If `raw` is false, the value will be unmarshalled.

get_multi(*keys)

Retrieves multiple values from memcached in parallel, if possible.

The memcached protocol supports the ability to retrieve multiple keys in a single request. Pass in an array of keys to this method and it will:

1. map the key to the appropriate memcached server
2. send a single request to each server that has one or more key values

Returns a hash of values.

      cache["a"] = 1
      cache["b"] = 2
      cache.get_multi "a", "b" # => { "a" => 1, "b" => 2 }

incr(key, amount = 1)

Increments the value for `key` by `amount` and retruns the new value. `key` must already exist. If `key` is not an integer, it is assumed to be 0.

inspect()

Returns a string representation of the cache object.

readonly?()

Returns whether or not the cache object was created read only.

reset()

Reset the connection to all memcache servers. This should be called if there is a problem with a cache lookup that might have left the connection in a corrupted state.

servers=(servers)

Set the servers that the requests will be distributed between. Entries can be either strings of the form "hostname:port" or "hostname:port:weight" or MemCache::Server objects.

set(key, value, expiry = 0, raw = false)

Add `key` to the cache with value `value` that expires in `expiry` seconds. If `raw` is true, `value` will not be Marshalled.

Warning: Readers should not call this method in the event of a cache miss; see MemCache#add.

stats()

Returns statistics for each memcached server. An explanation of the statistics can be found in the memcached docs:

code.sixapart.com/svn/memcached/trunk/server/doc/protocol.txt

Example:

      >> pp CACHE.stats
      {"localhost:11211"=>
        {"bytes"=>4718,
         "pid"=>20188,
         "connection_structures"=>4,
         "time"=>1162278121,
         "pointer_size"=>32,
         "limit_maxbytes"=>67108864,
         "cmd_get"=>14532,
         "version"=>"1.2.0",
         "bytes_written"=>432583,
         "cmd_set"=>32,
         "get_misses"=>0,
         "total_connections"=>19,
         "curr_connections"=>3,
         "curr_items"=>4,
         "uptime"=>1557,
         "get_hits"=>14532,
         "total_items"=>32,
         "rusage_system"=>0.313952,
         "rusage_user"=>0.119981,
         "bytes_read"=>190619}}
      => nil

### Protected Instance methods

cache_decr(server, cache_key, amount)

Performs a raw decr for `cache_key` from `server`. Returns nil if not found.

cache_get(server, cache_key)

Fetches the raw data for `cache_key` from `server`. Returns nil on cache miss.

cache_get_multi(server, cache_keys)

Fetches `cache_keys` from `server` using a multi-get.

cache_incr(server, cache_key, amount)

Performs a raw incr for `cache_key` from `server`. Returns nil if not found.

get_server_for_key(key)

Pick a server to handle the request based on a hash of the key.

handle_error(server, error)

Handles `error` from `server`.

hash_for(key)

Returns an interoperable hash value for `key`. (I think, docs are sketchy for down servers).

make_cache_key(key)

Create a key for the cache, incorporating the namespace qualifier if requested.

raise_on_error_response!(response)
request_setup(key)

Performs setup for making a request with `key` from memcached. Returns the server to fetch the key from and the complete key to use.

[Validate]