dreamcache Documentation
0.9
Introduction
dreamcache is an effective open source object caching system released under Apache License, Version 2.0. We provide our project in two parts: libdreamcache library and dreamcache server. libdreamcache was designed to be a high performance and thread-safe library that has a specified interface so that can be wrapped with your own server implementation. Server provides text protocol parsing and invokes methods from libdreamcache. It uses libevent to achieve good performance and to handle thousands of clients at the same time. The server starts a configurable amount of threads to process events and tries to assign threads to cores persistently to get extra boost. These two parts provide you with complete object caching environment that can be installed on server.Sourceforge dreamcache project
- Note:
- During previous release we decided to include a console which allowed you to test some of the library functions. Since we have created the server there seems no need to develop the console.
The purpose of using cache
If you are dealing with performance issues, e.g. your web application receives the amount of requests the database is unable to handle then fast memory cache is the solution to your problem. Dreamcache allows you to store objects under keys and then retrieve them. You can get great boost by setting up a cache server farm and sharing the load between machines.Life without dreamcache
Life with dreamcache
Main features of our product
- Users and Namespaces - our library allows you to create a kind of hierarchy; every cache user is capable of creating namespaces which can be explained as object's category. Two objects under the same key can be stored simultaneously in two separate namespaces.
- soft quota and hard quota per space - soft quota stands for the guaranteed amount of memory that space can always use for its objects, it can be and probably often will be exceeded. Hard quota is the top limit of memory for space, if exceeded, least recently used objects wil be removed in order to free memory.
- GarbageCollector - GC is in charge of removing expired objects and least recently used objects when memory limits are reached. Space Manager is a part of GC as well.
- SpaceManager - suppose you use more than one namespace and the load changes dynamically in time (e.g. one space is more active in the morning and the other is in the evening. Space manager provides load balancing facility between spaces based on the request statistics. It can dynamically assign more or less hard quota to space. It is important to know, that for every space soft quota is the guaranteed amount of memory which can be used by space any time it requires more memory, however when space's activity is so low that it cannot reach the soft quota, more active spaces can make use of this memory. This mechanism was designed so that space manager is not vulnerable to short peaks of activity and any more radical change in memory distribution per spaces requires more stable and long-term trends, e.g. one space is more active in the evenings and the other one is active at night. This prevents from many memory reassignments between spaces, which could kill the performance.
- Logger - both server and library are able to store logs in the configurable directory. However logging should be turned off when you need to achieve good performance. Considering libdreamcache library, you can set the logging level from 0 (no logging) to 3 (log everything). Level 3 is not recommended for typical use, it may cause a considerable slowdown, if you want to log critical events, use 1 or 2 level.
- multi thread support - many threads may execute requests on space at the same time, advanced exclusion mechanisms are provided to prevent race conditions but also keep synchronization overhead as low as possible. Furthermore, our server tries to permanently assign its worker threads to specific processor's cores to boost performance.
- binary protocol - which means less parsing overhead and therefore better performance.
Comparison with memcached - good old world-famous memory cache
During our test three servers based on Intel(R) Xeon(TM) 3.20 GHz, 2048KB cache processors were in use. Each server had 4GB of RAM. Tests were performed on linux kernel 2.6.20.16-kps-fc-m5r2, both memcached and dreamcache were built with gcc version 4.3.2, -O3 flag was also added during compilation. For testing we provide two testing client implementations - one is based on libevent and the other one uses libmemcached.Testing architecture is presented below.
For performance tests we set up dreamcache on one server and libmemcached-based client on two others. Both servers were using four worker threads. Each client was running 64 worker threads sending requests to server. Clients were managed through client manager started on the same machine as cache server. If not said explicitly, quota was set far above the need for the test. Set:Get proportion is given, eg. 1:10 means 10 Get requests per 1 Set request. Results are shown below.
As we can see from results above, dreamcache provides far better set request performance. Dreamcache's advantages are visible mostly while using small objects. The reason is very simple: the bigger the object becomes, the more time is spent on I/O operations and copying it. You can clearly see this problem in a chart below. That's why cache should be used where objects are small and accessed at high request rate.
Installation
dreamcache is divided into three sub-packages:- libdreamcache - the library
- dreamcache - the server which uses libdreamcache library
- dreamcache-tests - testing utilities that can be used to test dreamcache server
To install dreamcache to your system you just follow the usual GNU installation style.
Installing libdreamcache and its headers
$ ./configure --prefix=/usr --sysconfdir=/etc $ make $ make install
- Note:
- I set the install location of dreamcache (/usr) and system configuration directory which configuration files are installed to (/etc) both of witch are optional. Default prefix is '/usr/local' and default sysconfdir is '$(prefix)/etc'.
Installing libdreamcache with dreamcache server
In fact the server is built automatically. You can disable this feature by:
$ ./configure --disable-server $ make $ make install
Installing libdreamcache with testing utilities
$ ./configure --enable-tests $ make $ make install
Building dreamcache Debian package
There's a good information for Debian administrators. Now you can build a Debian package with dreamcache. All you have to do is:
$ dpkg-buildpackage
Configuration
All configuration files reside in $(sysconfdir)/dreamcache which dreamcache was configured with. Nevertheless, you are free to change their location by simply passing e.g. --sysconfdir=/etc to the configure script.libdreamcache configuration files include:
- config.cfg - general configuration
- users.cfg - user information (names and quotas) (currently unsupported)
dreamcache server configuration files include:
- server.cfg - everything related to the server
To find the meaning of the configurable variables go directly to the files. They have their short description next to every variable.
Running dreamcache
If you have dreamcache server already installed and configured you can run it by a simple command:
$ dreamcache
To change the configuration files location you can pass a single parameter with that directory:
$ dreamcache /home/jondoe/config
From that point the server is ready for caching data!
What's the protocol?
We decided to be 100% identical to memcached. Thanks to this, one can easily switch from memcached to dreamcache.We implemented both versions of their protocol:
- textual protocol - http://code.sixapart.com/svn/memcached/trunk/server/doc/protocol.txt
- binary protocol - http://code.google.com/p/memcached/wiki/MemcacheBinaryProtocol
Running tests
If you have dreamcache server and testing utilities already installed and configured:dreamcache-test-generator
Use dreamcache-test-generator to generate binary file which will be used as a key-value input during tests. To do so type:
$ dreamcache-test-generator <fileName> <reqCount> <minKeyLength> <maxKeyLength> <minObjectSize> <maxObjectSize>
where:
- fileName - desired output file name for testing data
- reqCount - determines how many key-value pairs should be generated
- minKeyLength, maxKeyLength - key length range (each of the generated keys has its size drawn from the range)
- minObjectSize, maxObjectSize - desired value lengths
dreamcache-test-client
Now start dreamcache server and then clients, type:
$ dreamcache-test-client <admin_port> <host> <port> <fileName> <threadCount> <getsPerSet> <timeout>
where:
- admin_port - port number on which client listens for commands such as: start, stop or stats
- host, port - server address
- fileName - input data generated with KeyValueGenerator
- threadCount - specifies how many threads should send requests to server
- getsPerSet - get:set proportion, for instance getsPerSet=10 means that an average of 10 gets is sent for 1 set request
or use clients based on libmemcached, in this case type:
$ dreamcache-test-lmclient <admin_port> <fileName> <threadCount> <getsPerSet> <timeout> <single_mode> <binary_mode> <host> <port> [<host> <port> ...]
where:
- admin_port - port number on which client listens for commands such as: start, stop or stats
- fileName - input data generated with KeyValueGenerator
- threadCount - specifies how many threads should send requests to server
- getsPerSet - get:set proportion, for instance getsPerSet=10 means that an average of 10 gets is sent for 1 set request
- single_mode - if set to 1 - client reconnects after every request, 0 means normal behaviour
- binary_mode - if set to 1 - client uses binary protocol in communication with server, if 0, text protocol is used
- host, port - server address (as you can see, this type of client can connect to more than one server simultaneously)
dreamcache-test-client-manager
The last thing to do is to use client-manager. It helps you to control clients from one central point. You can type:
$ dreamcache-test-client-manager <command> [client_ip ...] <administrative_port>
where:
- command can be:
- start - sends clients the signal to start sending requests
- stop - sends clients the signal to stop sending requests
- stats - gathers statistics from all clients, note: for proper time and performance statistics use stop command first and then stats
- [client_ip ...] consists of one or more client ip addresses
Authors
- Jacek Psiuk
- Damian Kiełbasa
- Filip Wójciak
- Grzegorz Łyczba
- Krzysztof Dębski
