diff --git a/ReadMe.adoc b/ReadMe.adoc index aa38d8228..a3ff98acc 100755 --- a/ReadMe.adoc +++ b/ReadMe.adoc @@ -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. -* <> - High level overview. -* <> - Features description. -* <> - Tutorial. -* <> - Frequently asked questions. -* <> - Downloading the software. -* <> - Updates from Chronicle Map version 2. -* <> - Versioning description. -* <> - 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 <> for more information. + +''' +== Documentation +The Chronicle Map documentation comprises: + +.Documentation +|=== +|**Document**|**Purpose** +|<> +|Features description. +|<> +|Tutorial. +|<> +|Frequently asked questions. +|<> +|Downloading the software. +|<> +|Updates from Chronicle Map version 2.|<> +|Replication explanation. +|<> +|Compatibility and Versioning description. +|=== + +Linked documentation is contained in the `docs` folder. \ No newline at end of file diff --git a/docs/CM_Compatibility_and_Versioning.adoc b/docs/CM_Compatibility_and_Versioning.adoc new file mode 100755 index 000000000..18a462c98 --- /dev/null +++ b/docs/CM_Compatibility_and_Versioning.adoc @@ -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 `` 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 `` 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 `` 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: + +`..` + +For example: +`3.14.1` + + +=== The 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 `` 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 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.-SNAPSHOT`. + + + +As soon as changes made that are substantial enough for the next released version +to update the `` number, then the version should be changed to `3..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 '' 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 `-pre` until the next production release. + +Releases and updates to the `` number in the library version should be synchronized with updates to the specification revision number. + + +''' +<<../ReadMe.adoc#,Back to ReadMe>> diff --git a/docs/CM_Features.adoc b/docs/CM_Features.adoc index 59371aead..1e464aaaf 100755 --- a/docs/CM_Features.adoc +++ b/docs/CM_Features.adoc @@ -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 <> for more information. + **Chronicle Map** has two meanings: - https://github.com/OpenHFT/Chronicle-Map/blob/master/spec[language-agnostic data store (specification)]. diff --git a/docs/CM_Overview.adoc b/docs/CM_Overview.adoc deleted file mode 100755 index 8b256f514..000000000 --- a/docs/CM_Overview.adoc +++ /dev/null @@ -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. - diff --git a/docs/CM_Compatibility.adoc b/docs/archived/CM_Compatibility.adoc similarity index 100% rename from docs/CM_Compatibility.adoc rename to docs/archived/CM_Compatibility.adoc diff --git a/docs/CM_Versioning.adoc b/docs/archived/CM_Versioning.adoc similarity index 100% rename from docs/CM_Versioning.adoc rename to docs/archived/CM_Versioning.adoc