memcachir v1.0.1 Memcachir

Module with a friendly API for memcached servers.

It provides connection pooling, and future cluster support.

Example

{:ok} = Memcachir.set("hello", "world")
{:ok, "world"} = Memcachir.get("hello")

Configuration

The following options can be customized (default shown):

config :memcachir
  # connection options
  hosts: ["localhost:11211"],
  backoff_initial: 500,
  backoff_max: 30_000,
  # memcached options
  ttl: 0,
  namespace: nil,
  coder: {Memcachir.Coder.Raw, []},
  # connection pool options
  strategy: :lifo,
  size: 10,
  max_overflow: 10

Coder

coder allows you to specify how the value should be encoded before sending it to the server and how it should be decoded after it is retrieved. There are four built-in coders namely Memcachir.Coder.Raw, Memcachir.Coder.Erlang, Memcachir.Coder.JSON, Memcachir.Coder.ZIP. Custom coders can be created by implementing the Memcachir.Coder behaviour.

CAS

CAS feature allows to atomically perform two commands on a key. Get the cas version number associated with a key during the first command and pass that value during the second command. The second command will fail if the value has changed by someone else in the mean time.

{:ok, "hello", cas} = Memcachir.get(pid, "key", cas: true)
{:ok} = Memcachir.set_cas(pid, "key", "world", cas)

Memcachir module provides a *_cas variant for most of the functions. This function will take an additional argument named cas and returns the same value as their counterpart except in case of CAS error. In case of CAS error the returned value would be equal to {:error, "Key exists"}

Options

Most of the functions in this module accept an optional Keyword list. The below list specifies the behavior of each option. The list of options accepted by a specific function will be documented in the specific funcion.

  • :cas - (boolean) returns the CAS value associated with the data. This value will be either in second or third position of the returned tuple depending on the command. Defaults to false.

  • :ttl - (integer) specifies the expiration time in seconds for the corresponding key. Can be set to 0 to disable expiration. The Default value can be set in config options.

Summary

Functions

Sets the key to value if the key doesn’t exist already. Returns {:error, "Key exists"} if the given key already exists

Appends the value to the end of the current value of the key. Returns {:error, "Item not stored"} if the item is not present in the server already

Appends the value to the end of the current value of the key if the CAS value is equal to the provided value

Compare and swap value using optimistic locking

Closes the connection to the memcached server

Gets the pid of a Memcachir.Connection process. Can be used to call functions in Memcachir.Connection

Decrements the current value. Only integer value can be decremented. Returns {:error, "Incr/Decr on non-numeric value"} if the value stored in the server is not numeric

Decrements the current value if the CAS value is equal to the provided value

Removes the item with the given key value. Returns { :error, "Key not found" } if the given key is not found

Removes the item with the given key value if the CAS value is equal to the provided value

Flush all the items in the server. ttl option will cause the flush to be delayed by the specified time

Gets the value associated with the key. Returns {:error, "Key not found"} if the given key doesn’t exist

Increments the current value. Only integer value can be incremented. Returns { :error, "Incr/Decr on non-numeric value"} if the value stored in the server is not numeric

Increments the current value if the CAS value is equal to the provided value

Sends a noop command

Prepends the value to the start of the current value of the key. Returns {:error, "Item not stored"} if the item is not present in the server already

Prepends the value to the start of the current value of the key if the CAS value is equal to the provided value

Sets the key to value if the key already exists. Returns {:error, "Key not found"} if the given key doesn’t exist

Sets the key to value if the key already exists and has CAS value equal to the provided value

Sets the key to value

Sets the key to value if the key exists and has CAS value equal to the provided value

Gets the specific set of server statistics

Gets the version of the server

Functions

add(key, value, opts \\ [])

Sets the key to value if the key doesn’t exist already. Returns {:error, "Key exists"} if the given key already exists.

Accepted options: :cas, :ttl

append(key, value, opts \\ [])

Appends the value to the end of the current value of the key. Returns {:error, "Item not stored"} if the item is not present in the server already

Accepted options: :cas

append_cas(key, value, cas, opts \\ [])

Appends the value to the end of the current value of the key if the CAS value is equal to the provided value

Accepted options: :cas

cas(key, update, opts \\ [])

Compare and swap value using optimistic locking.

  1. Get the existing value for key
  2. If it exists, call the update function with the value
  3. Set the returned value for key

The 3rd operation will fail if someone else has updated the value for the same key in the mean time. In that case, by default, this function will go to step 1 and try again. Retry behavior can be disabled by passing [retry: false] option.

close()

Closes the connection to the memcached server.

A new set of connections will be reopened automatically.

connection_pid()

Gets the pid of a Memcachir.Connection process. Can be used to call functions in Memcachir.Connection

decr(key, opts \\ [])

Decrements the current value. Only integer value can be decremented. Returns {:error, "Incr/Decr on non-numeric value"} if the value stored in the server is not numeric.

Options

  • :by - (integer) The amount to add to the existing value. Defaults to 1.

  • :default - (integer) Default value to use in case the key is not found. Defaults to 0.

other options: :cas, :ttl

decr_cas(key, cas, opts \\ [])

Decrements the current value if the CAS value is equal to the provided value.

Options

  • :by - (integer) The amount to add to the existing value. Defaults to 1.

  • :default - (integer) Default value to use in case the key is not found. Defaults to 0.

other options: :cas, :ttl

delete(key)

Removes the item with the given key value. Returns { :error, "Key not found" } if the given key is not found

delete_cas(key, cas)

Removes the item with the given key value if the CAS value is equal to the provided value

flush(opts \\ [])

Flush all the items in the server. ttl option will cause the flush to be delayed by the specified time.

Accepted options: :ttl

get(key, opts \\ [])

Gets the value associated with the key. Returns {:error, "Key not found"} if the given key doesn’t exist.

Accepted option: :cas

incr(key, opts \\ [])

Increments the current value. Only integer value can be incremented. Returns { :error, "Incr/Decr on non-numeric value"} if the value stored in the server is not numeric.

Options

  • :by - (integer) The amount to add to the existing value. Defaults to 1.

  • :default - (integer) Default value to use in case the key is not found. Defaults to 0.

other options: :cas, :ttl

incr_cas(key, cas, opts \\ [])

Increments the current value if the CAS value is equal to the provided value.

Options

  • :by - (integer) The amount to add to the existing value. Defaults to 1.

  • :default - (integer) Default value to use in case the key is not found. Defaults to 0.

other options: :cas, :ttl

noop()

Sends a noop command

prepend(key, value, opts \\ [])

Prepends the value to the start of the current value of the key. Returns {:error, "Item not stored"} if the item is not present in the server already

Accepted options: :cas

prepend_cas(key, value, cas, opts \\ [])

Prepends the value to the start of the current value of the key if the CAS value is equal to the provided value

Accepted options: :cas

replace(key, value, opts \\ [])

Sets the key to value if the key already exists. Returns {:error, "Key not found"} if the given key doesn’t exist.

Accepted options: :cas, :ttl

replace_cas(key, value, cas, opts \\ [])

Sets the key to value if the key already exists and has CAS value equal to the provided value.

Accepted options: :cas, :ttl

set(key, value, opts \\ [])

Sets the key to value

Accepted options: :cas, :ttl

set_cas(key, value, cas, opts \\ [])

Sets the key to value if the key exists and has CAS value equal to the provided value

Accepted options: :cas, :ttl

start(type, args)
stat(key \\ [])

Gets the specific set of server statistics

version()

Gets the version of the server