225 lines
8 KiB
ReStructuredText
225 lines
8 KiB
ReStructuredText
|
|
.. image:: https://travis-ci.org/arximboldi/immer.svg?branch=master
|
|
:target: https://travis-ci.org/arximboldi/immer
|
|
:alt: Travis Badge
|
|
|
|
.. image:: https://codecov.io/gh/arximboldi/immer/branch/master/graph/badge.svg
|
|
:target: https://codecov.io/gh/arximboldi/immer
|
|
:alt: CodeCov Badge
|
|
|
|
.. image:: https://cdn.rawgit.com/arximboldi/immer/355a113782aedc2ea22463444014809269c2376d/doc/_static/sinusoidal-badge.svg
|
|
:target: https://sinusoid.al
|
|
:alt: Sinusoidal Engineering badge
|
|
:align: right
|
|
|
|
.. raw:: html
|
|
|
|
<img width="100%" src="https://cdn.rawgit.com/arximboldi/immer/3888170d247359cc0905eed548cd46897caef0f4/doc/_static/logo-front.svg" alt="Logotype"/>
|
|
|
|
.. include:introduction/start
|
|
|
|
**immer** is a library of persistent_ and immutable_ data structures
|
|
written in C++. These enable whole new kinds of architectures for
|
|
interactive and concurrent programs of striking simplicity,
|
|
correctness, and performance.
|
|
|
|
.. _persistent: https://en.wikipedia.org/wiki/Persistent_data_structure
|
|
.. _immutable: https://en.wikipedia.org/wiki/Immutable_object
|
|
|
|
* **Documentation** (Contents_)
|
|
* **Code** (GitHub_)
|
|
* **CppCon'17 Talk**: *Postmodern Immutable Data Structures* (YouTube_, Slides_)
|
|
* **ICFP'17 Paper**: *Persistence for the masses* (Preprint_)
|
|
|
|
.. _contents: https://sinusoid.es/immer/#contents
|
|
.. _github: https://github.com/arximboldi/immer
|
|
.. _youtube: https://www.youtube.com/watch?v=sPhpelUfu8Q
|
|
.. _slides: https://sinusoid.es/talks/immer-cppcon17
|
|
.. _preprint: https://public.sinusoid.es/misc/immer/immer-icfp17.pdf
|
|
|
|
|
|
.. raw:: html
|
|
|
|
<a href="https://www.patreon.com/sinusoidal">
|
|
<img align="right" src="https://cdn.rawgit.com/arximboldi/immer/master/doc/_static/patreon.svg">
|
|
</a>
|
|
|
|
This library has full months of *pro bono* research and development
|
|
invested in it. This is just the first step in a long-term vision
|
|
of making interactive and concurrent C++ programs easier to
|
|
write. **Put your logo here and help this project's long term
|
|
sustainability by buying a sponsorship package:** immer@sinusoid.al
|
|
|
|
.. include:index/end
|
|
|
|
Example
|
|
-------
|
|
|
|
.. github does not support the ``literalinclude`` directive. This
|
|
example is copy pasted from ``example/vector/intro.cpp``
|
|
|
|
.. code-block:: c++
|
|
|
|
#include <immer/vector.hpp>
|
|
int main()
|
|
{
|
|
const auto v0 = immer::vector<int>{};
|
|
const auto v1 = v0.push_back(13);
|
|
assert(v0.size() == 0 && v1.size() == 1 && v1[0] == 13);
|
|
|
|
const auto v2 = v1.set(0, 42);
|
|
assert(v1[0] == 13 && v2[0] == 42);
|
|
}
|
|
..
|
|
|
|
For a **complete example** check `Ewig, a simple didactic
|
|
text-editor <https://github.com/arximboldi/ewig>`_ built with this
|
|
library. You may also wanna check `Lager, a Redux-like library
|
|
<https://github.com/arximboldi/lager>`_ for writting interactive
|
|
software in C++ using a value-oriented design.
|
|
|
|
|
|
Why?
|
|
----
|
|
|
|
In the last few years, there has been a growing interest in immutable
|
|
data structures, motivated by the horizontal scaling of our processing
|
|
power and the ubiquity of highly interactive systems. Languages like
|
|
Clojure_ and Scala_ provide them by default, and implementations
|
|
for JavaScript like Mori_ and Immutable.js_ are widely used,
|
|
specially in combination with modern UI frameworks like React_.
|
|
|
|
Interactivity
|
|
Thanks to *persistence* and *structural sharing*, new values can
|
|
be efficiently compared with old ones. This enables simpler ways of
|
|
*reasoning about change* that sit at the core of modern
|
|
interactive systems programming paradigms like `reactive
|
|
programming`_.
|
|
|
|
Concurrency
|
|
Passing immutable data structures by value does not need to copy
|
|
any data. In the absence of mutation, data can be safely read
|
|
from multiple concurrent processes, and enable concurrency
|
|
patterns like `share by communicating`_ efficiently.
|
|
|
|
Parallelism
|
|
Some recent immutable data structures have interesting properties
|
|
like :math:`O(log(n))` concatenation, which enable new kinds of
|
|
`parallelization algorithms`_.
|
|
|
|
.. _clojure: http://clojure.org/reference/data_structures
|
|
.. _scala: http://docs.scala-lang.org/overviews/collections/overview.html
|
|
|
|
.. _mori: https://swannodette.github.io/mori/
|
|
.. _immutable.js: https://github.com/facebook/immutable-js
|
|
.. _react: https://facebook.github.io/react/
|
|
|
|
.. _reactive programming: https://en.wikipedia.org/wiki/Reactive_programming
|
|
.. _share by communicating: https://blog.golang.org/share-memory-by-communicating
|
|
.. _parallelization algorithms: http://docs.scala-lang.org/overviews/parallel-collections/overview.html
|
|
|
|
Features
|
|
--------
|
|
|
|
Idiomatic
|
|
This library doesn't pretend that it is written in Haskell. It
|
|
leverages features from recent standards to provide an API that is
|
|
both efficient and natural for a C++ developer.
|
|
|
|
Performant
|
|
You use C++ because you need this. *Immer* implements state of
|
|
the art data structures with efficient cache utilization and have
|
|
been proven production ready in other languages. It also includes
|
|
our own improvements over that are only possible because of the
|
|
C++'s ability to abstract over memory layout. We monitor the
|
|
performance impact of every change by collecting `benchmark
|
|
results`_ directly from CI.
|
|
|
|
.. _benchmark results: https://public.sinusoid.es/misc/immer/reports/
|
|
|
|
Customizable
|
|
We leverage templates and `policy-based design`_ to build
|
|
data-structures that can be adapted to work efficiently for
|
|
various purposes and architectures, for example, by choosing among
|
|
various `memory management strategies`. This turns
|
|
*immer* into a good foundation to provide immutable data
|
|
structures to higher level languages with a C runtime, like
|
|
Python_ or Guile_.
|
|
|
|
.. _python: https://www.python.org/
|
|
.. _guile: https://www.gnu.org/software/guile/
|
|
.. _policy-based design: https://en.wikipedia.org/wiki/Policy-based_design
|
|
.. _memory management strategies: https://sinusoid.es/immer/memory.html
|
|
|
|
Dependencies
|
|
------------
|
|
|
|
This library is written in **C++14** and a compliant compiler is
|
|
necessary. It is `continuously tested`_ with Clang 3.8 and GCC 6, but
|
|
it might work with other compilers and versions.
|
|
|
|
No external library is necessary and there are no other requirements.
|
|
|
|
.. _continuously tested: https://travis-ci.org/arximboldi/immer
|
|
|
|
Usage
|
|
-----
|
|
|
|
This is a **header only** library. You can just copy the ``immer``
|
|
subfolder somewhere in your *include path*.
|
|
|
|
If you are using the `Nix package manager`_ (we strongly recommend it)
|
|
you can just::
|
|
|
|
nix-env -if https://github.com/arximboldi/immer/archive/master.tar.gz
|
|
|
|
Alternatively, you can use `CMake`_ to install the library in your
|
|
system once you have manually cloned the repository::
|
|
|
|
mkdir -p build && cd build
|
|
cmake .. && sudo make install
|
|
|
|
.. _nix package manager: https://nixos.org/nix
|
|
.. _cmake: https://cmake.org/
|
|
|
|
Development
|
|
-----------
|
|
|
|
In order to develop the library, you will need to compile and run the
|
|
examples, tests and benchmarks. These require some additional tools.
|
|
The easiest way to install them is by using the `Nix package
|
|
manager`_. At the root of the repository just type::
|
|
|
|
nix-shell
|
|
|
|
This will download all required dependencies and create an isolated
|
|
environment in which you can use these dependencies, without polluting
|
|
your system.
|
|
|
|
Then you can proceed to generate a development project using `CMake`_::
|
|
|
|
mkdir build && cd build
|
|
cmake ..
|
|
|
|
From then on, one may build and run all tests by doing::
|
|
|
|
make check
|
|
|
|
In order to build and run all benchmarks when running ``make check``,
|
|
run ``cmake`` again with the option ``-DCHECK_BENCHMARKS=1``. The
|
|
results of running the benchmarks will be saved to a folder
|
|
``reports/`` in the project root.
|
|
|
|
License
|
|
-------
|
|
|
|
**This software is licensed under the Boost Software License 1.0**.
|
|
|
|
.. image:: https://upload.wikimedia.org/wikipedia/commons/c/cd/Boost.png
|
|
:alt: Boost logo
|
|
:target: http://boost.org/LICENSE_1_0.txt
|
|
:align: right
|
|
|
|
The full text of the license is can be accessed `via this link
|
|
<http://boost.org/LICENSE_1_0.txt>`_ and is also included
|
|
in the ``LICENSE`` file of this software package.
|