Repository files navigation

immer is a library ofpersistent andimmutable data structureswritten in C++. These enable whole new kinds of architectures forinteractive and concurrent programs of striking simplicity,correctness, and performance.

• Documentation (Contents)
• Code (GitHub)
• CppCon'17 Talk:Postmodern Immutable Data Structures (YouTube,Slides)
• ICFP'17 Paper:Persistence for the masses (Preprint)

This library has full months ofpro bono research and developmentinvested in it. This is just the first step in a long-term visionof making interactive and concurrent C++ programs easier towrite.Put your logo here and help this project's long termsustainability by buying a sponsorship package:immer@sinusoid.al

#include<immer/vector.hpp>intmain(){constauto v0 = immer::vector<int>{};constauto v1 = v0.push_back(13);assert(v0.size() ==0 && v1.size() ==1 && v1[0] ==13);constauto v2 = v1.set(0,42);assert(v1[0] ==13 && v2[0] ==42);}

For acomplete example checkEwig, a simple didactictext-editor built with thislibrary. You may also wanna checkLager, a Redux-like library for writing interactivesoftware in C++ using a value-oriented design.

In the last few years, there has been a growing interest in immutabledata structures, motivated by the horizontal scaling of our processingpower and the ubiquity of highly interactive systems. Languages likeClojure andScala provide them by default, and implementationsfor JavaScript likeMori andImmutable.js are widely used,specially in combination with modern UI frameworks likeReact.

Interactivity

Thanks topersistence andstructural sharing, new values canbe efficiently compared with old ones. This enables simpler ways ofreasoning about change that sit at the core of moderninteractive systems programming paradigms likereactiveprogramming.

Concurrency

Passing immutable data structures by value does not need to copyany data. In the absence of mutation, data can be safely readfrom multiple concurrent processes, and enable concurrencypatterns likeshare by communicating efficiently.

Parallelism

Some recent immutable data structures have interesting propertieslikeO(log(n)) concatenation, which enable new kinds ofparallelization algorithms.

Idiomatic

This library doesn't pretend that it is written in Haskell. Itleverages features from recent standards to provide an API that isboth efficient and natural for a C++ developer.

Performant

You use C++ because you need this.Immer implements state ofthe art data structures with efficient cache utilization and havebeen proven production ready in other languages. It also includesour own improvements over that are only possible because of theC++'s ability to abstract over memory layout. We monitor theperformance impact of every change by collectingbenchmarkresults directly from CI.

Customizable

We leverage templates andpolicy-based design to builddata-structures that can be adapted to work efficiently forvarious purposes and architectures, for example, by choosing amongvarious memory management strategies. This turnsimmer into a good foundation to provide immutable datastructures to higher level languages with a C runtime, likePython orGuile.

This library is written inC++14 and a compliant compiler isnecessary. It iscontinuously tested with Clang 3.8 and GCC 6, butit might work with other compilers and versions.

No external library is necessary and there are no other requirements.

This is aheader only library. You can just copy theimmersubfolder somewhere in yourinclude path.

If you are using theNix package manager (we strongly recommend it)you can just:

nix-env -if https://github.com/arximboldi/immer/archive/master.tar.gz

Alternatively, you can useCMake to install the library in yoursystem once you have manually cloned the repository:

mkdir -p build && cd buildcmake .. && sudo make install

You can download and install immer using the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager:

git clone https://github.com/Microsoft/vcpkg.gitcd vcpkg./bootstrap-vcpkg.sh./vcpkg integrate install./vcpkg install immer

The immer port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please [create an issue or pull request](https://github.com/Microsoft/vcpkg) on the vcpkg repository.

In order to develop the library, you will need to compile and run theexamples, tests and benchmarks. These require some additional tools.The easiest way to install them is by using theNix packagemanager. At the root of the repository just type:

nix-shell

This will download all required dependencies and create an isolatedenvironment in which you can use these dependencies, without pollutingyour system.

Then you can proceed to generate a development project usingCMake:

mkdir build && cd buildcmake ..

From then on, one may build and run all tests by doing:

make check

In order to build and run all benchmarks when runningmake check,runcmake again with the option-DCHECK_BENCHMARKS=1. Theresults of running the benchmarks will be saved to a folderreports/ in the project root.

This software is licensed under the Boost Software License 1.0.

The full text of the license is can be accessedvia this link and is also includedin theLICENSE file of this software package.