Dalli

Dalli is a high performance pure Ruby client for accessing memcached servers.

Dalli supports:

• Simple and complex memcached configurations
• Failover between memcached instances
• Fine-grained control of data serialization and compression
• Thread-safe operation (either through use of a connection pool, or by using the Dalli client in threadsafe mode)
• SSL/TLS connections to memcached
• SASL authentication

The name is a variant of Salvador Dali for his famous painting The Persistence of Memory.

Documentation and Information

• User Documentation - The documentation is maintained in the repository's wiki.
• Announcements - Announcements of interest to the Dalli community will be posted here.
• Bug Reports - If you discover a problem with Dalli, please submit a bug report in the tracker.
• Forum - If you have questions about Dalli, please post them here.
• Client API - Ruby documentation for the Dalli::Client API

Optional response correlation

Enable single-get response validation with Dalli::Client.new(servers, correlate_with_opaques: true). Dalli uses the first caller-supplied O token in meta_flags, or generates a four-character (24-bit) token if none is supplied. It sends that token exactly once and checks the echoed value against it.

Mismatched or missing tokens on accepted get replies return a miss and close the connection, without retrying or down-marking. Other protocol errors are unchanged. Omit the option or set it to false to leave caller opaques and default reads unchanged. Caller tokens must be protocol-safe and suitably unique per request; reused tokens cannot detect swaps between those requests. Multi-get/pipeline behavior is unchanged.

For opt-in, per-request opaque correlation, also set opaque_correlation_request_only: true on the client and pass correlate_with_opaques: true in request options. The PRNG is still initialized at connection setup, but unflagged requests retain their baseline behavior:

client = Dalli::Client.new(servers, correlate_with_opaques: true, opaque_correlation_request_only: true)
client.get('key')                             # no correlation
client.get('key', correlate_with_opaques: true) # correlate this read

Request-only mode defaults to false. Requests can explicitly opt out with correlate_with_opaques: false in either mode, but cannot enable correlation when the client option is false or omitted. An omitted or nil request option inherits the client mode. Request options do not mutate client configuration. They also apply to gat, CAS reads, get_with_status, touch, and the reads made by fetch/cas!.

Experimental: timeout recovery under fiber schedulers

Under a fiber scheduler, socket_timeout is enforced by a scheduler timer that starts when a read begins to wait. If another fiber keeps the thread busy past that deadline, a scheduler can run the expired timer before it delivers the readiness of a reply that has already arrived. The read then fails, the connection is closed, and the reply is lost.

Pass exp_async_timeout_recovery: true in request options to read that request's response through a connection-local buffer with an explicit deadline on each wait. When a wait expires, Dalli polls the socket once more, outside the scheduler, before it reports a timeout:

client.get('key', exp_async_timeout_recovery: true)
client.get_multi('a', 'b', exp_async_timeout_recovery: true)
client.set('key', 'value', nil, exp_async_timeout_recovery: true)

The option defaults to false, and requests without it read exactly as before. A reply that does not arrive still fails after socket_timeout. Writes are unchanged, and so is the pipelined get_multi path used with multiple servers or a block. The buffer is about 8 KiB per connection, is allocated only when a request on that connection opts in, and is released when the connection closes. The exp_ prefix marks the option as experimental.

Development

After checking out the repo, run bin/setup to install dependencies. You can run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Contributing

If you have a fix you wish to provide, please fork the code, fix in your local project and then send a pull request on github. Please ensure that you include a test which verifies your fix and update the changelog with a one sentence description of your fix so you get credit as a contributor.

Appreciation

Dalli would not exist in its current form without the contributions of many people. But special thanks go to several individuals and organizations:

• Mike Perham - for originally authoring the Dalli project and serving as maintainer and primary contributor for many years
• Eric Wong - for help using his kgio library.
• Brian Mitchell - for his remix-stash project which was helpful when implementing and testing the binary protocol support.
• CouchBase - for their sponsorship of the original development

Authors

• Peter M. Goldstein - current maintainer
• Mike Perham and contributors

Copyright

Copyright (c) Mike Perham, Peter M. Goldstein. See LICENSE for details.