Dalli::Client Options

In addition to the Server Configuration, described here, the Dalli::Client can take a number of options that impact its behavior.

Memcached and Client-level Options

• namespace (string, default nil) - if specified, prepend each key with this value to provide simple namespacing.
• expires_in (int, default 0) - default TTL for memcached entries in seconds. Can be overridden on a per-request basis. Default value of 0 corresponds to no expiration.
• cache_nils (bool, default false) - if true Dalli will not treat cached nil values as 'not found' for #fetch operations.
• value_max_bytes (int, default 1024 * 1024) - maximum allowed size in bytes for a memcached entry. The default value for memcached is 1 MB, but this can be adjusted with the -I parameter. If the value is adjusted in memcached, the corresponding value should be specified for value_max_bytes.
• threadsafe (bool, default true) - if true the Dalli::Client can be safely shared between threads. In many use cases it makes sense to use a connection pool of Dalli::Client objects, in which case this should be set to false.
• digest_class (class implementing hexdigest, Digest::MD5) - a class used to "truncate" keys that would otherwise exceed the maximum allowed key length for memcached (250) while maintaining uniqueness. In general this option should not be specified unless MD5 cannot be used for compliance reasons.
• protocol (:binary or :meta, default is :binary) - as of 3.2.0 users of Dalli can configure it to use the meta protocol when communicating with memcached by setting the protocol option to :meta

Compression and Serialization Options

• serializer (class implementing dump/load, default Marshal) - class used to serialize Ruby values to memcached. Can be overridden on a per-request basis with the raw option, which will call to_s on the value being serialized rather than passing it to the Serializer class.
• compress (bool, default true) - if true, compress values inserted into memcached that exceed the compression_min_size.
• compression_min_size (int, default 4 * 1024) - if the compress option is true, values whose bytesize exceeds this value will be compressed when inserted into memcached.
• compressor (class implementing compress/decompress, Dalli::Compressor) - if the compress option is true, this class is used to compress and decompress values sent to and from memcached respectively. The default Compressor uses zlib compression.
  • If serving compressed data using nginx's HttpMemcachedModule, set memcached_gzip_flag 2 and use Dalli::GzipCompressor

Failover / Retry Options

• failover (bool, default true) - if true, Dalli will attempt to failover requests for a key to a different server if the primary server corresponding to that key is unreachable.
• socket_max_failures (int, default 2) - the maximum number of consecutive network failures before a server is marked as down.
• socket_failure_delay (float, default 0.1) - the number of seconds the current thread will sleep before attempting a reconnect
• down_retry_delay (int, default 30) - once a server is marked as down, this is the minimum number of seconds Dalli will wait before checking if the server is reachable again. If set too low, each request which tries the failed server might hang for the maximum socket_timeout

Socket Options

• keepalive (bool, default true) - if true, keepalive is enabled for the memcached sockets
• sndbuf (int, default nil) - if not nil sets the SO_RCVBUF for the TCP socket to the value in bytes. Otherwise the SO_SNDBUF value is left as the operating system default.
• rcvbuf (int, default nil) - if not nil sets the SO_RCVBUF for the TCP socket to the value in bytes. Otherwise the SO_SNDBUF value is left as the operating system default.
• ssl_context (instance of OpenSSL::SSL::SSLContext, default nil) - if not nil, Dalli will attempt to use the specified SSLContext object to create SSL/TLS connections to the memcached servers.
• socket_timeout (int, default 1) - timeout for socket operations. For pipelined operations like get_multi and get_multi_cas, this is the timeout for the whole operation and not a single socket read.

SASL Authentication Options

• username (string, default nil) - the username for SASL authentication. If not nil, then Dalli will attempt to authenticate with SASL to the memcached server. May also be specified on a per-server basis using the URI form of the server configuration.
• password (string, default nil) - the password for SASL authentication. May also be specified on a per-server basis using the URI form of the server configuration.