What is Chronicle Map

Chronicle Map is a high performance, off-heap, key-value, in memory, persisted data store. It works like a  standard java map yet it automatically distributes data between processes, these processes can be both on the same server or across your network. In other words its a low latency, huge data key value store, which can store terabytes of data locally to your process.

Chronicle Map diagram_04It is able to access this data with sub-micro-second latency. Chronicle is built on Java but it does not undergo, the garbage collection pauses, which most Java applications experience.  This is because chronicle stores your data off heap. Even if you have a large cache with lots of updates, the garbage collector will have almost no effect; resulting in more predictable latency and throughput. The off heap data is stored in a memory mapped file, which offers further resilience to unforeseen outages.

Over Your Network

Chronicle Map doesn’t just span a number of Java processes on the same server, It is able to replicate data across your network via TCP/IP or UDP, Each Chronicle Map will hold a local copy of the data, so get()’s are blisteringly fast. Our reconciliation algorithm keeps all the maps across your network in sync. This reconciliation focuses on low latency, so put()’s are not blocked by the network layer. – find out more


Multiple Chronicle Maps, Network Distributed

With chronicle you can store hundreds of maps on each server, Chronicle replication will ensure that all the maps  are kept in sync, To reduce the overhead of having a large number of maps we have crafted chronicle so that all the maps share the same tcp connection – adding additional maps won’t create additional socket connections – find out more


Broadcast with UDP

With UDP, the message is only sent once. This is ideal if you have a large number of hosts and you wish to broadcast the same data to each off them. However, one of the big drawbacks with UDP is its not a reliable protocol. This means, if the UDP message is Broadcast onto the network, The hosts are not guaranteed to receive it, so they can miss data. Some solutions attempt to build resilience into UDP, but arguably, this is in effect reinventing TCP/IP.

In reality on a good quality wired LAN, when using UDP, you will rarely miss messages, this is a risk that we suggest you don’t take. We suggest that whenever you use UDP replication you use it in conjunction with a throttled TCP replication, therefore if a host misses a message over UDP, they will later pick it up via TCP/IP. – find out more


Screen Shot 2014-10-24 at 12.53.29

Stateless Client

With “Chronicle Map over your network” your data is replicated across a distributed grid of servers, for the best performance your business logic can run on any of these servers, In this configuration you will get lightning fast performance as your data will be resident to your process. However sometimes you may wish to run your business logic on a separate sever which does not have a replica of all your data. So we created a stateless Chronicle Map client.

With the stateless client you are able to perform Remote Procedure Calls ( RPC ) to your map remotely via TCP/IP. We refer to these clients as stateless clients as they don’t hold the data locally. In other words, The method calls you make on the stateless client are transmitted over TCP/IP to a remote server. The remote server holds all the data, your request is applied to the server, the results are then sent back to your client over TCP/IP. – find out more


How it works

wrenchYou define the structure of the entries you wish to store and set the maximum number of entries. Chronicle will create and appropriately sized memory mapped file, say 4TB.  The size of the memory mapped file is not constrained by physical memory, so unlike heap based key value stores, chronicle eliminates the pauses that can occur when the store has to be resized.

If your data grid spans two or more processes on the same server, each process will share the same 4TB space, fine grain locking will ensure that your data integrity. The data is transferred directly using shared memory, when replicating on the same server we don’t use TCP/IP loopback, which will add additional latency, we just use memory. This approach gives you outstanding performance, we have measured data being transferred between processes in a staggering 40 nanoseconds.

For solutions that require replication across your network, we provide both TCP and UDP connectivity. Chronicle uses Java NIO selectors, so only one thread is used to replicate to numerous processes.


Chronicle Map offers :

  • High throughput, low latency,  cross process, persisted key value store.
  • Supports very high update rates by only replicating the latest value.
  • Off heap data storage, with micro second latency.
  • Designed to be used in Java, in a pause less, garbage free manner.
  • Easy to adopt and open source based on the ConcurrentHashMap.
  • Better utilizes your existing hardware by offering vertical scalability.
  • UDP support for high fan out.
  • TCP connectivity.
  • Concurrent writers on one machine using one copy in memory.
  • Concurrent multi-master writers across machines, with a reconciliation process.
  • Multiple readers with TCP and UDP replication.
  • Resilient writes ( if a process dies, the last write is not lost. )
  • Entirely embedded, you don’t need any additional processes.


It is an ideal choice if :

  • You require the latest value based on a key.
  • Your update rate can exceeds the rate consumers can consume the data.
  • You have limited Network bandwidth.


Chronicle Map has been tested to do

  • 30 million updates per second with 500 million key-values on a 16 core machine, with a 64 MB heap and no minor collections.
  • multi way multi-mastering
  • 1.6 million updates per second replicated across a low bandwidth between two laptops.
  • A ping-pong test between processes of 25 million per second. One process set a flag from false to true, the other from true to false.
  • Data is not lost even if the JVM crashes on the next line.

Find out more…

Peter Lawrey talks about shared memory in java and Chronicle Map performance *

* Chronicle Map used to be called Shared Hash Map

For More Information

GitHubSource Code
Source Code DocumentationJavaDoc
Getting StartedTutorial
Stack OverflowQuestion