Chronicle-Map/docs/CM_Features.adoc

= Chronicle Map - Features
Neil Clifford
:toc: macro
:toclevels: 1
:css-signature: demo
:toc-placement: macro
:icons: font

toc::[]

Chronicle Map is an in-memory, key-value store, designed for low-latency, and/or multi-process
applications such as trading and financial market applications.

== Features
 - **Ultra low latency**: Chronicle Map targets median latency of both read and write queries of less
 than 1 *micro*second in https://github.com/OpenHFT/Chronicle-Map/search?l=java&q=perf&type=Code[certain tests].

 - **High concurrency**: Write queries scale well up to the number of hardware execution threads in
 the server. Read queries never block each other.
 - **Persistence to disk** - (Optional)
 - **Multi-key queries** - (Optional, closed-source) - Eventually-consistent, fully-redundant, asynchronous replication across
 servers, "last write wins" strategy by default, allows to implement custom https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type[state-based CRDT] strategy.

== Unique features
 - Multiple processes could access a Chronicle Map concurrently. At the same time,
 the data store is *in-process for each of the accessing processes*. (Out-of-process approach to IPC
 is simply incompatible with Chronicle Map's median latency target of < 1 μs.)

 - Replication *without logs*, with constant footprint cost, guarantees progress even if the network
 doesn't sustain write rates.

**Chronicle Map** has two meanings:

- https://github.com/OpenHFT/Chronicle-Map/blob/master/spec[language-agnostic data store (specification)].

- https://github.com/OpenHFT/Chronicle-Map/blob/master/src[implementation of this data store for the JVM (source)]. Currently, this is the only implementation.

=== From Java perspective
`ChronicleMap` is a `ConcurrentMap` implementation which stores the
entries *off-heap*, serializing/deserializing key and value objects to/from off-heap memory
transparently. Chronicle Map supports:

 - Key and value objects caching/reusing for making *zero allocations (garbage) on
queries*.
 - Flyweight values for eliminating serialization/deserialization cost and allowing direct
 read/write access to off-heap memory.

=== Primary Chronicle Map use cases**

 - Replacing slower key-value stores, like `Redis` and `Memcached`, when used within a single server.
 - Replacing similar JVM-centric solutions, like `Coherence` and `Hazelcast`, for speed and/or certain Chronicle Map features those solutions lack.
 - Moving parts of the application state out of the Java heap for either:
 * Reducing the heap size, for reducing GC pressure, or fitting 32 GB for using `CompressedOops`.
 * Inter-process communication.
 * Persistence`
 * Replication across servers.

 - Drop-in `ConcurrentHashMap` replacement, Chronicle Map performs better in some cases.

=== What guarantees does Chronicle Map provide in ACID terms?

 - Atomicity - single-key queries are atomic if Chronicle Map is properly configured, multi-key
 queries are not atomic.
 - Consistency - doesn't make sense for key-value stores
 - Isolation - yes (for both single- and multi-key queries).
 - Durability - no, Chronicle Map can be persisted to disk but with no guarantee as to to how frequently this
 happens - this is under the control of the OS. All data is guaranteed to be written to disk when the Map is closed.
 - Clustering and replication for Chronicle
 Map is provided by http://chronicle.software/products/chronicle-map/[Chronicle Map Enterprise].

**Project status: ready for production.**

== What is the Chronicle Map's data structure?
Simply put, a Chronicle Map data store is a big chunk of shared memory (optionally mapped to disk).

It is split into independent segments; each segment has:

 - an independent memory allocation for storing the entries,
 - a hash table for search
 - a lock in shared memory (implemented via CAS loops) for managing concurrent access.

Read [the Chronicle Map data store design overview](spec/2-design-overview.md) for more information.

== Chronicle Map is not:

 - A document store. No secondary indexes.
 - A https://en.wikipedia.org/wiki/Multimap[multimap].
 Using a Chronicle Map collection as multimap is technically possible, but often leads to problems. See http://stackoverflow.com/a/36486525/648955[StackOverflow answer] for details.
 Developing a proper multimap with
 Chronicle Map's design principles is possible,

Please contact us at mailto:sales@chronicle.software[sales@chronicle.software] if
 you would consider sponsoring such development.

== Chronicle Map does not support:

 - Range queries
 - Iteration over the entries in alphabetical order.
 - sorting of keys.
 - LRU entry eviction.

== Features

.Features
|===
|Feature |Availability

|In-memory off-heap Map
|Open-source
|Persistence to disk
|Open-source
|Remote calls
|http://chronicle.software/products/chronicle-map/[Closed-source]
|Eventually-consistent replication (100% redundancy
|http://chronicle.software/products/chronicle-map/[Closed-source]
|Synchronous replication
|http://chronicle.software/products/chronicle-map/[Closed-source]
|Partially-redundant replication
|http://chronicle.software/consultancy/[On-demand]
|Entry expiration timeouts
|http://chronicle.software/consultancy/[On-demand]

|===

== Peer projects
 - https://github.com/OpenHFT/Chronicle-Engine[Chronicle Engine].  Reactive processing framework
 supporting Chronicle Map as a backend.
 - http://chronicle.software/products/chronicle-enterprise/[Chronicle Enterprise]. Extended
 version of Chronicle Engine.
 - http://vanillajava.blogspot.com/2015/09/chronicle-journal-customizable-data.html[Chronicle Journal]. Another
 key-value built by Chronicle Software, with different properties.

== Community support:
 - https://github.com/OpenHFT/Chronicle-Map/issues[Issues]
 - https://groups.google.com/forum/#!forum/chronicle-map[Chronicle Map mailing list]
 - http://stackoverflow.com/tags/chronicle-map[Stackoverflow]
 - https://plus.google.com/communities/111431452027706917722[Chronicle User's group]
 - http://jrvis.com/red-dwarf/?user=openhft&repo=Chronicle-Map[Chronicle Map usage heatmap]


'''
<<../ReadMe.adoc#,Back to ReadMe>>