memcachex v0.4.1 Memcache
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" }
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 tofalse
.:ttl
- (integer) specifies the expiration time in seconds for the corresponding key. Can be set to0
to disable expiration. The Default value can be configured usingstart_link/2
.
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
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
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
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 version of set/4
. Accepts a map or a list of {key, value}
Multi version of set_cas/4
. Accepts a list of {key, value, cas}
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
Creates a connection using Memcache.Connection.start_link/2
Gets the default set of server statistics
Gets the specific set of server statistics
Closes the connection to the memcached server
Gets the version of the server
Types
Functions
add(GenServer.server, binary, binary, 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
append(GenServer.server, binary, binary, 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
append_cas(GenServer.server, binary, binary, 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
cas(GenServer.server, binary, (binary -> binary), Keyword.t) :: {:ok, any} | error
Compare and swap value using optimistic locking.
- Get the existing value for key
- If it exists, call the update function with the value
- 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.
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 to1
.:default
- (integer) Default value to use in case the key is not found. Defaults to0
.
other options: :cas
, :ttl
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 to1
.:default
- (integer) Default value to use in case the key is not found. Defaults to0
.
other options: :cas
, :ttl
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.
Accepted options: :ttl
Gets the value associated with the key. Returns {:error, "Key not
found"}
if the given key doesn’t exist.
Accepted option: :cas
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 to1
.:default
- (integer) Default value to use in case the key is not found. Defaults to0
.
other options: :cas
, :ttl
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 to1
.:default
- (integer) Default value to use in case the key is not found. Defaults to0
.
other options: :cas
, :ttl
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
multi_set(GenServer.server, [{binary, binary}] | 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
multi_set_cas(GenServer.server, [{binary, binary, integer}], Keyword.t) :: {:ok, [store_result]} | error
Multi version of set_cas/4
. Accepts a list of {key, value, cas}
.
Accepted options: :cas
, :ttl
Sends a noop command
prepend(GenServer.server, binary, binary, 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
prepend_cas(GenServer.server, binary, binary, 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
replace(GenServer.server, binary, binary, 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
replace_cas(GenServer.server, binary, binary, 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
set(GenServer.server, binary, binary, Keyword.t) :: store_result
Sets the key to value
Accepted options: :cas
, :ttl
set_cas(GenServer.server, binary, binary, 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
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 to0
(means forever).:namespace
- (string) prepend each key with the given value.: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.
Gets the default set of server statistics
Gets the specific set of server statistics
Closes the connection to the memcached server.
Gets the version of the server