memcachex

v0.5.0

memcachex v0.5.0 Memcache View Source

This module provides a user friendly API to interact with the memcached server.

Example 

{:ok, pid} = Memcache.start_link()
{:ok} = Memcache.set(pid, "hello", "world")
{:ok, "world"} = Memcache.get(pid, "hello")

Coder

Memcache.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 retrived. There are four built-in coders namely Memcache.Coder.Raw, Memcache.Coder.Erlang, Memcache.Coder.JSON, Memcache.Coder.ZIP. Custom coders can be created by implementing the Memcache.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} = Memcache.get(pid, "key", cas: true)
{:ok} = Memcache.set_cas(pid, "key", "world", cas)

Memcache 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"}

Telemetry

The following telemetry events are published:

  • [:memcachex, :commands] - executed for every successful commands

    • Measurements

      • :elapsed_time - (integer - native time unit) the time it took to send the commands to the server and get a reply.

    • Metadata

      • :server - (binary) hostname and port of the server
      • :commands - (list) list of command
      • :results - (list) list of response from the server
      • :start_time - (integer - native time unit) system time when the commands were issued

  • [:memcachex, :commands_error] - executed for every failed commands

    • Measurements

      • :elapsed_time - (integer - native time unit) the time it took to send the commands to the server and get a reply.

    • Metadata

      • :server - (binary) hostname and port of the server
      • :commands - (list) list of command
      • :reason - (atom) error reason
      • :start_time - (integer - native time unit) system time when the commands were issued

  • [:memcachex, :connection] - executed after successful connection.

    • Metadata

      • :server - (binary) hostname and port of the server
      • :reconnected - (boolean) set to true for reconnection

  • [:memcachex, :connection_error] - executed on connection failure.

    • Metadata

      • :server - (binary) hostname and port of the server
      • :reason - (atom) error reason

Options

Most the functions in this module accept an optional Keyword list. The below list specifies the behavior of each option. The list of option 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 configured using start_link/2.

Link to this section Summary

Types

error()
fetch_integer_result()
fetch_result()
result()
store_result()
value()

Functions

add(server, 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.

append(server, 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

append_cas(server, 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

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

Compare and swap value using optimistic locking.

decr(server, key, opts \\ [])

Decremens 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.

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

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

delete(server, key)

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

delete_cas(server, key, cas)

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

flush(server, opts \\ [])

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

get(server, key, opts \\ [])

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

incr(server, 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.

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

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

multi_get(server, keys, opts \\ [])

Gets the values associated with the list of keys. Returns a map. Keys that are not found in the server are filtered from the result.

multi_set(server, commands, opts \\ [])

Multi version of set/4. Accepts a map or a list of {key, value}.

multi_set_cas(server, commands, opts \\ [])

Multi version of set_cas/4. Accepts a list of {key, value, cas}.

noop(server)

Sends a noop command

prepend(server, 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

prepend_cas(server, 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

replace(server, 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.

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

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

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

Sets the key to value

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

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

start_link(connection_options \\ [], options \\ [])

Creates a connection using Memcache.Connection.start_link/2

stat(server)

Gets the default set of server statistics

stat(server, key)

Gets the specific set of server statistics

stop(server)

Closes the connection to the memcached server.

version(server)

Gets the version of the server

Link to this section Types

Link to this type

error() View Source 
error() :: {:error, binary() | atom()}

Link to this type

fetch_integer_result() View Source 
fetch_integer_result() ::
  {:ok, integer()} | {:ok, integer(), integer()} | error()

Link to this type

fetch_result() View Source 
fetch_result() :: {:ok, any()} | {:ok, any(), integer()} | error()

Link to this type

result() View Source 
result() ::
  {:ok} | {:ok, integer()} | {:ok, any()} | {:ok, any(), integer()} | error()

Link to this type

store_result() View Source 
store_result() :: {:ok} | {:ok, integer()} | error()

Link to this type

value() View Source 
value() :: term()

Link to this section Functions

Link to this function

add(server, key, value, opts \\ []) View Source 
add(GenServer.server(), binary(), value(), Keyword.t()) :: store_result()

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

Link to this function

append(server, key, value, opts \\ []) View Source 
append(GenServer.server(), binary(), value(), Keyword.t()) :: store_result()

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

Link to this function

append_cas(server, key, value, cas, opts \\ []) View Source 
append_cas(GenServer.server(), binary(), value(), integer(), Keyword.t()) ::
  store_result()

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

Link to this function

cas(server, key, update, opts \\ []) View Source 
cas(GenServer.server(), binary(), (value() -> value()), Keyword.t()) ::
  {:ok, any()} | error()

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.

Link to this function

decr(server, key, opts \\ []) View Source 
decr(GenServer.server(), binary(), Keyword.t()) :: fetch_integer_result()

Decremens 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

Link to this function

decr_cas(server, key, cas, opts \\ []) View Source 
decr_cas(GenServer.server(), binary(), integer(), Keyword.t()) ::
  fetch_integer_result()

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

Link to this function

delete(server, key) View Source 
delete(GenServer.server(), binary()) :: store_result()

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

Link to this function

delete_cas(server, key, cas) View Source 
delete_cas(GenServer.server(), binary(), integer()) :: store_result()

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

Link to this function

flush(server, opts \\ []) View Source 
flush(GenServer.server(), Keyword.t()) :: store_result()

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

Accepted options: :ttl

Link to this function

get(server, key, opts \\ []) View Source 
get(GenServer.server(), binary(), Keyword.t()) :: fetch_result()

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

Accepted option: :cas

Link to this function

incr(server, key, opts \\ []) View Source 
incr(GenServer.server(), binary(), Keyword.t()) :: fetch_integer_result()

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

Link to this function

incr_cas(server, key, cas, opts \\ []) View Source 
incr_cas(GenServer.server(), binary(), integer(), Keyword.t()) ::
  fetch_integer_result()

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

Link to this function

multi_get(server, keys, opts \\ []) View Source 
multi_get(GenServer.server(), [binary()], Keyword.t()) ::
  {:ok, map()} | error()

Gets the values associated with the list of keys. Returns a map. Keys that are not found in the server are filtered from the result.

Accepted option: :cas

Link to this function

multi_set(server, commands, opts \\ []) View Source 
multi_set(GenServer.server(), [{binary(), value()}] | map(), Keyword.t()) ::
  {:ok, [store_result()]} | error()

Multi version of set/4. Accepts a map or a list of {key, value}.

Accepted options: :cas, :ttl

Link to this function

multi_set_cas(server, commands, opts \\ []) View Source 
multi_set_cas(GenServer.server(), [{binary(), value(), integer()}], Keyword.t()) ::
  {:ok, [store_result()]} | error()

Multi version of set_cas/4. Accepts a list of {key, value, cas}.

Accepted options: :cas, :ttl

Link to this function

noop(server) View Source 
noop(GenServer.server()) :: {:ok} | error()

Sends a noop command

Link to this function

prepend(server, key, value, opts \\ []) View Source 
prepend(GenServer.server(), binary(), value(), Keyword.t()) :: store_result()

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

Link to this function

prepend_cas(server, key, value, cas, opts \\ []) View Source 
prepend_cas(GenServer.server(), binary(), value(), integer(), Keyword.t()) ::
  store_result()

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

Link to this function

replace(server, key, value, opts \\ []) View Source 
replace(GenServer.server(), binary(), value(), Keyword.t()) :: store_result()

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

Link to this function

replace_cas(server, key, value, cas, opts \\ []) View Source 
replace_cas(GenServer.server(), binary(), value(), integer(), Keyword.t()) ::
  store_result()

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

Accepted options: :cas, :ttl

Link to this function

set(server, key, value, opts \\ []) View Source 
set(GenServer.server(), binary(), value(), Keyword.t()) :: store_result()

Sets the key to value

Accepted options: :cas, :ttl

Link to this function

set_cas(server, key, value, cas, opts \\ []) View Source 
set_cas(GenServer.server(), binary(), value(), integer(), Keyword.t()) ::
  store_result()

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

Accepted options: :cas, :ttl

Link to this function

start_link(connection_options \\ [], options \\ []) View Source 
start_link(Keyword.t(), Keyword.t()) :: GenServer.on_start()

Creates a connection using Memcache.Connection.start_link/2

Connection Options

This is a superset of the connection options accepted by the Memcache.Connection.start_link/2. The following list specifies the additional options.

  • :ttl - (integer) a default expiration time in seconds. This value will be used if the :ttl value is not specified for a operation. Defaults to 0(means forever).

  • :namespace - (string) prepend each key with the given value.

  • :key_coder - ({module, function}) Used to transform the key completely. The function needs to accept one argument, the key and return a new key.

  • :coder - (module | {module, options}) Can be either a module or tuple contains the module and options. Defaults to {Memcache.Coder.Raw, []}.

Options

The second option is passed directly to the underlying GenServer.start_link/3, so it can be used to create named process.

Link to this function

stat(server) View Source 
stat(GenServer.server()) :: {:ok, map()} | error()

Gets the default set of server statistics

Link to this function

stat(server, key) View Source 
stat(GenServer.server(), String.t()) :: {:ok, map()} | error()

Gets the specific set of server statistics

Link to this function

stop(server) View Source 
stop(GenServer.server()) :: {:ok}

Closes the connection to the memcached server.

Link to this function

version(server) View Source 
version(GenServer.server()) :: String.t() | error()

Gets the version of the server