mirror of
https://github.com/OpenHFT/Chronicle-Map.git
synced 2021-09-13 01:26:12 +00:00
Initial re-work of documentation
This commit is contained in:
Neil Clifford
+71
-16
@@ -1,28 +1,83 @@
|
||||
= Chronicle MAP
|
||||
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.
|
||||
|
||||
The Chronicle Map documentation comprises the following:
|
||||
Chronicle Map is a super-fast, in-memory, key-value store, designed for low-latency, and/or multi-process applications such as trading and financial market applications.
|
||||
|
||||
* `ReadMe.adoc` - This file.
|
||||
* <<docs/CM_Overview.adoc#,CM_Overview.adoc>> - High level overview.
|
||||
* <<docs/CM_Features.adoc#,CM_Features.adoc>> - Features description.
|
||||
* <<docs/CM_Tutorial.adoc#,CM_Tutorial.adoc>> - Tutorial.
|
||||
* <<docs/CM_FAQs.adoc#,CM_FAQs.adoc>> - Frequently asked questions.
|
||||
* <<docs/CM_Download.adoc#,CM_Download.adoc>> - Downloading the software.
|
||||
* <<docs/CM_Updates.adoc#,CM_Updates.adoc>> - Updates from Chronicle Map version 2.
|
||||
* <<docs/CM_Versioning.adoc#,CM_Versioning.adoc>> - Versioning description.
|
||||
* <<docs/CM_Compatibility.adoc#,CM_Compatibility.adoc>> - Compatibility description.
|
||||
Chronicle Map can overflow seamlessly to disk, and can be distributed across the network.
|
||||
|
||||
Linked documentation is contained in the `docs` folder.
|
||||
image::docs\images\CM_Overview.jpg[]
|
||||
|
||||
== Prerequisites
|
||||
|
||||
To run this evaluation, please ensure you have first installed:
|
||||
To run Chronicle Map, please ensure you have first installed:
|
||||
|
||||
* Java (1.8.0_91 or later)
|
||||
* Apache Maven (3.2.3 or later)
|
||||
|
||||
== Our thanks
|
||||
=== Use cases
|
||||
Chronicle Map is used in production around the
|
||||
world for:
|
||||
|
||||
Chronicle Software would like to thank you for taking the time to evaluate Chronicle Map, and we hope that you will see the benefits that a fully tailored and supported installation will bring your organisation.
|
||||
• **real-time trading systems**. Chronicle Map
|
||||
provides in-memory access speeds, and supports
|
||||
ultra-low garbage collection. Chronicle Map can support the most demanding of applications.
|
||||
• **highly concurrent systems**. Chronicle Map
|
||||
supports multiple readers and writers,
|
||||
distributed across multiple machines.
|
||||
|
||||
=== Why use Chronicle Map?
|
||||
Chronicle Map is:
|
||||
|
||||
• **fast**. Millions of operations per second, with
|
||||
low and stable microsecond latencies.
|
||||
• **reliable**. Chronicle Software have a “chaos
|
||||
monkey” test which verifies Chronicle Map
|
||||
multi-master replication in the face of node
|
||||
and network failures.
|
||||
• **in production** at banks and hedge funds,
|
||||
globally.
|
||||
• **built using lessons learnt** from real-world
|
||||
experience solving real-world problems.
|
||||
• **open source** (standard version), and in use at
|
||||
hundreds of sites around the world.
|
||||
|
||||
=== Our offering
|
||||
Chronicle Software provide full support for
|
||||
Chronicle Map, consulting to help you make
|
||||
best use of the product, and can also deliver
|
||||
projects using a mix of our resources and
|
||||
your own.
|
||||
|
||||
=== Replication Environment Example
|
||||
The following diagram shows an example of Chronicle Map replication over three servers (or sites).
|
||||
|
||||
image::docs\images\Configure_Three_Way_Replication.png[]
|
||||
|
||||
Replication is multi-master, lock-free, redundant, deterministic, and eventually consistent.
|
||||
|
||||
The writer can optionally wait for replication to occur across nodes or regions.
|
||||
|
||||
NOTE: See <<docs/CM_Replication.adoc#,Chronicle Map Replication>> for more information.
|
||||
|
||||
'''
|
||||
== Documentation
|
||||
The Chronicle Map documentation comprises:
|
||||
|
||||
.Documentation
|
||||
|===
|
||||
|**Document**|**Purpose**
|
||||
|<<docs/CM_Features.adoc#,CM_Features.adoc>>
|
||||
|Features description.
|
||||
|<<docs/CM_Tutorial.adoc#,CM_Tutorial.adoc>>
|
||||
|Tutorial.
|
||||
|<<docs/CM_FAQs.adoc#,CM_FAQs.adoc>>
|
||||
|Frequently asked questions.
|
||||
|<<docs/CM_Download.adoc#,CM_Download.adoc>>
|
||||
|Downloading the software.
|
||||
|<<docs/CM_Updates.adoc#,CM_Updates.adoc>>
|
||||
|Updates from Chronicle Map version 2.|<<docs/CM_Replication.adoc#,CM_Replication.adoc>>
|
||||
|Replication explanation.
|
||||
|<<docs/CM_Compatibility_and_Versioning.adoc#,CM_Compatibility_and_Versioning>>
|
||||
|Compatibility and Versioning description.
|
||||
|===
|
||||
|
||||
Linked documentation is contained in the `docs` folder.
|
||||
Executable
+115
@@ -0,0 +1,115 @@
|
||||
= Chronicle Map Compatibility and Versioning
|
||||
Neil Clifford
|
||||
:toc: macro
|
||||
:toclevels: 1
|
||||
:css-signature: demo
|
||||
:toc-placement: macro
|
||||
:icons: font
|
||||
|
||||
toc::[]
|
||||
|
||||
== Java Implementation Compatibility
|
||||
|
||||
=== Public API
|
||||
|
||||
The *public API* comprises public classes that are included in
|
||||
http://www.javadoc.io/doc/net.openhft/chronicle-map/[Javadoc].
|
||||
|
||||
NOTE: Other public classes are not subject to
|
||||
the following rules; they may be changed in any way, or even removed.
|
||||
|
||||
- Class and method names, types, and number of parameters in already existing methods, should not be changed.
|
||||
- Any methods can be added to the classes and interfaces that are not subject for
|
||||
subclassing or implementing by the library users; such as `ChronicleMap`, `ChronicleMapBuilder`,
|
||||
`MapEntry`. They must be added in such a way that any existing code calling methods on those classes still compile; and not
|
||||
break due to ambiguity in method resolution.
|
||||
- Only non-abstract (concrete or default) methods can be added to the classes and interfaces that are subject for subclassing by the library users; such as `MapMethods`, `MapEntryOperations`, `SizedReader`.
|
||||
|
||||
=== Behaviour
|
||||
|
||||
Semantics and actual effects of API calls may change between Chronicle Map versions with
|
||||
different `<minor>` number versioning. For example, default serialization forms of key or value objects of some types could change, "high level" configurations in `ChronicleMapBuilder` could produce
|
||||
Chronicle Maps with different "low level" configurations, etc.
|
||||
|
||||
Such changes should be documented in the release notes.
|
||||
|
||||
=== Persistence File Binary Form
|
||||
|
||||
A persisted Chronicle Map store (a binary file), produced by a production release of the library, should be accessible and updatable by any subsequent production release of the library in the `3.x` branch; unless the older version has bugs that lead to data corruption.
|
||||
|
||||
To support this:
|
||||
|
||||
- Serialization forms of any classes should not be changed. For example, when a marshaller class (say, `StringBytesReader`) of objects of some type is changed and its serialization form should be changed, a new class called `StringBytesReader_3_5` (5 is the `<minor>` number of the version of the library, in which this change is made) should be created, and put along with older class.
|
||||
|
||||
- When the specification revision is updated (hence binary form could be completely changed), a new version of the root implementation class (say, `VanillaChronicleMap_3_5`) should be created and put along with older version, which should behave the same as before.
|
||||
|
||||
=== Replication Protocol
|
||||
|
||||
The replication protocol may change between Chronicle Map versions with different `<minor>` numbers.
|
||||
|
||||
Chronicle Map nodes should communicate with other nodes of the same version.
|
||||
|
||||
Chronicle Map nodes running different versions of the library should not communicate to each other. This may lead to failures, but not to data corruption on either of the nodes.
|
||||
|
||||
== Specification Compatibility
|
||||
|
||||
The Chronicle Map Data Store specification can be updated without changing the revision while it remains backward compatible; that is, the implementation of the newer version of the specification can access and update any persisted Chronicle Map store, produced by an older version.
|
||||
In addition, potential *concurrent* accessing implementations of older versions ("within" the same revision) should not lose correctness and corrupt the data.
|
||||
|
||||
If more substantial changes to the specification are required, the revision number should be updated.
|
||||
|
||||
The binary form of Chronicle Map and its algorithms could change between revisions to any degree, but <<../spec/1-design-goals.md#guarantees,guarantees>> provided by the specification are not weakened.
|
||||
|
||||
== Java implementation Versioning
|
||||
|
||||
The versioning format is as follows:
|
||||
|
||||
`<major>.<minor>.<patch>`
|
||||
|
||||
For example:
|
||||
`3.14.1`
|
||||
|
||||
|
||||
=== The <minor> number should be updated, when:
|
||||
|
||||
- **a feature, or public API** method is added.
|
||||
|
||||
- **the behaviour** of `ChronicleMap`, `ChronicleMapBuilder`, or any other class or method or subsystem, is semantically changed.
|
||||
For example, when configuration heuristics in `ChronicleMapBuilder` are improved, and
|
||||
`ChronicleMapBuilder` configured the same way constructs a `ChronicleMap` with a different number of segments, or segment's capacity.
|
||||
|
||||
- **any dependency is updated**; even if only the `<patch>` number is updated. For example, `chronicle-bytes` dependency is updated from `1.1.1` to `1.1.2`. +
|
||||
This rule does not apply to dependencies to the umbrella POMs which merely determine versions of other dependencies (namely, `chronicle-bom` and `third-party-bom`), if the versions of actual dependencies do not change between those versions of umbrella POMs. +
|
||||
Also, this rule does not apply to dependencies with Maven scopes of `test` or `provided`.
|
||||
|
||||
- **bug fixes, performance optimization, or feature additions** that requires changes to:
|
||||
** the binary, or serialized, form of Chronicle Map data store; therefore revising the Chronicle Map data store specification.
|
||||
** the binary replication protocol, or the serialized form of some marshaller classes, that require creation of new versions of classes.
|
||||
|
||||
=== The <minor> number should not be updated (that is, the next release could update only the "patch" number) when:
|
||||
- **a bug fixed**, in a way that doesn't make any working code to change its behaviour semantically.
|
||||
- **performance is optimized**, changing its performance characteristics,
|
||||
but not semantics.
|
||||
|
||||
During development, and after the release of the version `3.y.z`, the library should be versioned `3.y.<x+1>-SNAPSHOT`. +
|
||||
+
|
||||
As soon as changes made that are substantial enough for the next released version
|
||||
to update the `<minor>` number, then the version should be changed to `3.<y+1>.0-SNAPSHOT`, *in the same
|
||||
commit operation* that these changes are made.
|
||||
|
||||
Suffixes `-alpha`, `-beta`, `-rc`, mean it is a pre-production release.
|
||||
|
||||
== Specification Versioning
|
||||
|
||||
The first Chronicle Map 3 production release designates the Chronicle Map data store specification; revision 1.
|
||||
|
||||
When the specification needs to be updated in a way that is not [backward compatible](compatibility.md#the-specification-compatibility), the revision should be updated (revision `2`, `3`, ...) and the Java implementation of this revision should have its '<minor>' version number updated.
|
||||
|
||||
During development, and after the release of the revision `x`, while the specification is backward compatible, it should remain versioned `x`. In the same commit operation where the specification becomes
|
||||
incompatible, its revision should be set to `<x+1>-pre` until the next production release.
|
||||
|
||||
Releases and updates to the `<minor>` number in the library version should be synchronized with updates to the specification revision number.
|
||||
|
||||
|
||||
'''
|
||||
<<../ReadMe.adoc#,Back to ReadMe>>
|
||||
@@ -23,12 +23,15 @@ applications such as trading and financial market applications.
|
||||
|
||||
== 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.)
|
||||
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.
|
||||
|
||||
|
||||
NOTE: See <<docs/CM_Replication.adoc#,Chronicle Map Replication>> for more information.
|
||||
|
||||
**Chronicle Map** has two meanings:
|
||||
|
||||
- https://github.com/OpenHFT/Chronicle-Map/blob/master/spec[language-agnostic data store (specification)].
|
||||
|
||||
@@ -1,50 +0,0 @@
|
||||
= Chronicle Map overview
|
||||
|
||||
Chronicle Map is a super-fast, in-memory, key-value
|
||||
store, that can overflow seamlessly to disk, and can be distributed across the network.
|
||||
|
||||
image::images\CM_Overview.jpg[]
|
||||
|
||||
== Use cases
|
||||
Chronicle Map is used in production around the
|
||||
world for:
|
||||
|
||||
• **real-time trading systems**. Chronicle Map
|
||||
provides in-memory access speeds, and supports
|
||||
ultra-low garbage collection. Chronicle Map can support the most demanding of applications.
|
||||
• **highly concurrent systems**. Chronicle Map
|
||||
supports multiple readers and writers,
|
||||
distributed across multiple machines.
|
||||
|
||||
== Why use Chronicle Map?
|
||||
Chronicle Map is:
|
||||
|
||||
• fast. Millions of operations per second, with
|
||||
low and stable microsecond latencies.
|
||||
• built using lessons learnt from real-world
|
||||
experience solving real-world problems.
|
||||
• open source (standard version), and in use at
|
||||
hundreds of sites around the world.
|
||||
• in production at banks and hedge funds,
|
||||
globally.
|
||||
• reliable. Chronicle Software have a “chaos
|
||||
monkey” test which verifies Chronicle Map
|
||||
multi-master replication in the face of node
|
||||
and network failures.
|
||||
|
||||
== Our offering
|
||||
Chronicle Software provide full support for
|
||||
Chronicle Map, consulting to help you make
|
||||
best use of the product, and can also deliver
|
||||
projects using a mix of our resources and
|
||||
your own.
|
||||
|
||||
== Replication Environment Example
|
||||
The following diagram shows an example of Chronicle Map replication over 3 servers (or sites).
|
||||
|
||||
image::images\Configure_Three_Way_Replication.png[]
|
||||
|
||||
Replication is multi-master, lock-free, redundant, deterministic, and eventually consistent.
|
||||
|
||||
The writer can optionally wait for replication to occur across nodes or regions.
|
||||
|
||||
Reference in New Issue
Block a user