dreamcache Documentation



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

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

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, 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.



dreamcache is divided into three sub-packages:

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 

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 


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:

dreamcache server configuration files include:

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:

Running tests

If you have dreamcache server and testing utilities already installed and configured:


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> 



Now start dreamcache server and then clients, type:

 $ dreamcache-test-client <admin_port> <host> <port> <fileName> <threadCount> <getsPerSet> <timeout> 


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> ...] 



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> 



Contact with us

Please give us a feedback on dreamcache. We are dying to know what you think. E-mail addresses can be easily found in the dreamcache manual.


dreamcache is licensed under the Apache License, Version 2.0 which you can obtain from:

Generated on Fri Jan 8 10:38:12 2010 for dreamcache by  doxygen 1.5.5