MemcachedClient Configuration

You have two options to configure the MemcachedClient:

• using the app.config,
• providing an object which implements IMemcachedClientConfiguration

App.config (or web.config) is recommended when your pool is static or you rarely change it. Use the programmatic configuration (either implementing the interface or just using the MemcachedClientConfiguration) when your application has a custom configuration mechanism and you need to integrate memcached there.

App.config

This is a full configuration file:

	<?xml version="1.0" encoding="utf-8" ?>
	<configuration>
	  <configSections>
	    <sectionGroup name="enyim.com">
	      <section name="memcached" type="Enyim.Caching.Configuration.MemcachedClientSection, Enyim.Caching" />
	    </sectionGroup>
	  </configSections>
	
	  <enyim.com>
	    <memcached protocol="Binary|Text">
	      <servers>
	        <!-- make sure you use the same ordering of nodes in every configuration you have -->
	        <add address="ip address" port="port number" />
	        <add address="ip address" port="port number" />
	      </servers>
	      <socketPool minPoolSize="integer" maxPoolSize="integer" connectionTimeout="timespan" deadTimeout="timespan" />
	      <locator type="fully qualified type name" factory="fully qualified type name" />
	      <transcoder type="fully qualified type name" factory="fully qualified type name" />
	      <keyTransformer type="fully qualified type name" factory="fully qualified type name" />
	      <performanceMonitor type="fully qualified type name" factory="fully qualified type name" />
	    </memcached>
	  </enyim.com>
	</configuration>

All elements are optional except where specified.

enyim.com/memcached

This section is used as default, if no other config is provided to the client.

• protocol (optional): Specify which protocol the client should use to communicate with the server. Binary is recommended, unless you're using an ancient version of Memcached (1.4 or below). The default is Binary.

memcached/servers (required)

Add each of your memcached server's address and port here. Both IP addresses and host names are supported.

Make sure you use the same order in every configuration you have in the application (for example on each web server in your cluster), otherwise the consistent hashing algorithm may assign items to nodes differently.

memcached/socketPool

Defines how the client should handle the connections to the Memcached servers. All attributes are optional.

• minPoolSize: The minimum number of connections opened to each Memcached server. Default is 10.
• maxPoolSize: The maximum number of connections that can be opened to each Memcached server. Default is 20.
• connectionTimeout: The amount of time the client is waiting to establish a connection to the memcached server. If it times out the current operation will fail and the node will be marked as unresponsive. Default is 00:00:10.
• deadTimeout: The amount of time the client is waiting to check the state of an unresponsive node. Default is 00:00:10.
• queueTimeout: The amount of time the client is waiting to acquire a socket when the pool reached maxPoolSize. If it times out the current operation will fail and the node will be marked as unresponsive. Default is 00:00:00.100 (100msecs). New in 2.8+

Both minPoolSize and maxPoolSize must be greater than zero. The recommended value for maxPoolSize is 0.75 * (number of threads) to avoid thread starvation when one of the nodes becomes unresponsive.

The connection pool works the following way:

1. When the client is initialized, it opens minPoolSize connections to each server defined in memcached/servers. The client will wait for connectionTimeout to establish a connection. If it expires, the node will be marked as dead.
2. Each operation takes a socket from the pool
3. If the pool has no unused connection but it did not reach maxPoolSize, then a new socket will be created. The client will wait for connectionTimeout to establish the connection. If it expires, the node will be marked as dead.
4. If the pool has no unused connection and it did reach maxPoolSize (a semaphore is used to track this), the client will wait for queueTimeout. If it still cannot acquire one, the node will be marked as dead. The the pool only gets full when a) maxPoolSize is to low while the load is high, or b) a node goes down. A low value here ensures that the application will not eat up all threads while waiting for all connections to timeout when a node goes down.
5. The first time a node goes down a timer will be started which will periodically (see deadTimeout) check the marked nodes if they are available. The timer will be stopped when all nodes come online.

Note: maxPoolSize had a much larger value in 2.6 and below. Until you can upgrade it's recommended to set to the optimal value in your configuration files manually (see above).

memcached/locator

Used to map objects to servers in the pool. Either type or factory must be provided (factory takes precedence if both are specified).

• type must be the fully qualified name of a Type implementing IMemcachedNodeLocator
• factory must be the fully qualified name of a Type implementing IProviderFactory<IMemcachedNodeLocator>

The following locators are included by default:

• Enyim.Caching.DefaultNodeLocator, Enyim.Caching The default locator, provides consistent hashing.
• Enyim.Caching.KetamaNodeLocator, Enyim.Caching Ketama locator, compatible with spymemcached. Uses MD5 for the hash ring. Additionally this can be specified using a factory, Enyim.Caching.KetamaNodeLocatorFactory, Enyim.Caching, so it can use different hash algorithms:

	<locator factory="Enyim.Caching.KetamaNodeLocatorFactory, Enyim.Caching"
		hashName="md5|sha1|tiger|crc|fnv1_32|fnv1_64|fnv1a_32|fnv1a_64|murmur|oneatatime" />

See also IProviderFactory.

memcached/keyTransformer

Used to normalize/validate the item keys before sending them to the server. Either type or factory must be provided (factory takes precedence if both are specified).

• type must be the fully qualified name of a Type implementing IMemcachedKeyTransformer
• factory must be the fully qualified name of a Type implementing IProviderFactory<IMemcachedKeyTransformer>

The following transformers are included by default:

• Enyim.Caching.Memcached.DefaultKeyTransformer, Enyim.Caching It does not change the keys, only checks for invalid characters. (ASCII code < 32)
• Enyim.Caching.Memcached.TigerHashKeyTransformer, Enyim.Caching Uses TigerHash to hash the keys. Faster than SHA1, recommended when using long (> 150 chars) keys.
• Enyim.Caching.Memcached.SHA1KeyTransformer, Enyim.Caching Uses SHA1 to hash the keys.
• Enyim.Caching.Memcached.Base64KeyTransformer, Enyim.Caching Uses base-64 encoding on the item keys.

See also IProviderFactory.

memcached/transcoder

Used to serialize stored/retrieved objects. Either type or factory must be provided (factory takes precedence if both are specified).

• type must be the fully qualified name of a Type implementing ITranscoder
• factory must be the fully qualified name of a Type implementing IProviderFactory<ITranscoder>

See also IProviderFactory.

memcached/performanceMonitor

Used to define a performance monitor instance which can provide statistics about the client. Either type or factory must be provided (factory takes precedence if both are specified). See Configure the Performance Monitor about enabling this feature.

• type must be the fully qualified name of a Type implementing IPerformanceMonitor
• factory must be the fully qualified name of a Type implementing IProviderFactory<IPerformanceMonitor>

See also IProviderFactory.

IMemcachedClientConfiguration

You should implement this interface if you want to provide your own configuration mechanisms (for example, reading the config from the database), or you just need more flexibility.

There is a default implementation included: Enyim.Caching.Configuration.MemcachedClientConfiguration. Its properties correspond with the attributes above.