abs / mcd

Fast memcached protocol client in pure Erlang

		Erlang memcached client library.

This library provides two ways of working with memcached servers. One way
is to use a single server, as described in #1. Another way is to use a number
of memcached servers in a consistent hashing mode. This is described in #2.


1. RUNNING IN SINGLE-SERVER MODE

1.1  Starting a single memcached

The following will start the anonymous mcd client,
addressable by the returned pid().

	mcd:start_link(["localhost", 11211]).

The next one will connect to the memcached server on the local host,
and will also register the mcd instance under the 'myMcd' name. See 3.
The mcd API can use the returned pid() and the registered name interchangeably.

	mcd:start_link(myMcd, []).
	mcd:set(myMcd, a, b).
	mcd:get(myMcd, a).

The 'localmcd' name is a special convention, allowing mcd API to be used
without the explicit mcd process specification.

	unlink(element(2, mcd:start_link(localmcd, []))).
	mcd:set(a, b).
	mcd:get(a).

1.2  A ChildSpec for running the mcd named 'localmcd' under a supervisor

	{ localmcd, { mcd, start_link,
	  [localmcd, ["localhost", 11211] ] },
	  permanent, 10000, worker, [mcd] }


2. RUNNING IN CLUSTERED MODE

   mcd_starter starts a set of of memcached instances and mcd_cluster
   dispatcher attached to them. All memcached instances and mcd_cluster
   are linked to this gen_server, so a proper exit hierarchy is formed.

2.1  Starting memcached cluster from the command line (e.g., for testing)

	mcd_starter:start_link(mainCluster,
		[ ["remoteHost1", 11211], ["remoteHost2", 1890] ]).

2.2  A ChildSpec for running the cluster named 'mainCluster' under a supervisor

	{ mainCluster, { mcd_starter, start_link, [mainCluster, [
			["remoteHost1"],
			["remoteHost2", 1890] ] },
		permanent, infinity, supervisor, [mcd_starter] }

     Note: the default port for "remoteHost1" is 11211.


3. USING MEMCACHED

	{ok, b} = mcd:set(localmcd, a, b).
	{error, notfound} = mcd:get(localmcd, foo).
	{ok, [42]} = mcd:set(mainCluster, <<"bar">>, [42]).
	{ok, [42]} = mcd:get(mainCluster, <<"bar">>).

By convention, you can omit specifying 'localmcd' (see 1.2):

	{ok, alive} = mcd:set(self(), alive).
	{ok, alive} = mcd:get(self()).