readme.md

   1 CDS C++ library\r
   2 ===============\r
   3 [![GitHub version](https://badge.fury.io/gh/khizmax%2Flibcds.svg)](http://badge.fury.io/gh/khizmax%2Flibcds)\r
   4 [![License](https://img.shields.io/:license-bsd-blue.svg?style=round-square)](https://github.com/khizmax/libcds/blob/master/LICENSE)\r
   5 [![Build Status](https://travis-ci.org/khizmax/libcds.svg?branch=dev)](https://travis-ci.org/khizmax/libcds)\r
   6 \r
   7 <!---\r
   8 The coverity dataset is about 4G of size and about 1G in compressed state so it is a problem to upload it to the coverity server\r
   9 [![Coverity Scan Build Status](https://scan.coverity.com/projects/4445/badge.svg)](https://scan.coverity.com/projects/4445)\r
  10 -->\r
  11 \r
  12 The Concurrent Data Structures (CDS) library is a collection of concurrent containers\r
  13 that don't require external (manual) synchronization for shared access, and safe memory reclamation (SMR) \r
  14 algorithms like [Hazard Pointer](http://en.wikipedia.org/wiki/Hazard_pointer) \r
  15 and user-space [RCU](http://en.wikipedia.org/wiki/Read-copy-update) that is used as an epoch-based SMR.\r
  16 \r
  17 CDS is mostly header-only template library. Only SMR core implementation is segregated to .so/.dll file.\r
  18 \r
  19 The library contains the implementations of the following containers:\r
  20   - [lock-free](http://en.wikipedia.org/wiki/Non-blocking_algorithm) stack with optional elimination support\r
  21   - several algo for lock-free queue, including classic Michael & Scott algorithm and its derivatives,\r
  22     the flat combining queue, the segmented queue.\r
  23   - several implementation of unordered set/map - lock-free and fine-grained lock-based\r
  24   - [flat-combining](http://mcg.cs.tau.ac.il/projects/projects/flat-combining) technique\r
  25   - lock-free [skip-list](http://en.wikipedia.org/wiki/Skip_list)\r
  26   - lock-free FeldmanHashMap/Set [Multi-Level Array Hash](http://samos-conference.com/Resources_Samos_Websites/Proceedings_Repository_SAMOS/2013/Files/2013-IC-20.pdf)\r
  27     with thread-safe bidirectional iterator support\r
  28   - Bronson's et al algorithm for fine-grained lock-based AVL tree\r
  29   \r
  30 Generally, each container has an intrusive and non-intrusive (STL-like) version belonging to \r
  31 *cds::intrusive* and *cds::container* namespace respectively. \r
  32 \r
  33 Version 2.x of the library is written on C++11 and can be compiled by GCC 4.8+, clang 3.6+, Intel C++ 15+, \r
  34 and MS VC++ 12 (2013) Update 4 and above\r
  35 \r
  36 Download the latest release from http://sourceforge.net/projects/libcds/files/\r
  37 \r
  38 See online doxygen-generated doc here: http://libcds.sourceforge.net/doc/cds-api/index.html\r
  39 \r
  40 Evolution of libcds (Gource visualization by Landon Wilkins): https://www.youtube.com/watch?v=FHaJvVdmJ0w\r
  41 \r
  42 **How to build**\r
  43    - *nix: [use CMake](build/cmake/readme.md)\r
  44    - Windows: use MS Visual C++ 2015 project\r
  45 \r
  46 Some parts of libcds may depend on DCAS (double-width compare-and-swap) atomic primitive if\r
  47 the target architecture supports it. For x86, cmake build script enables `-mcx16` compiler flag that\r
  48 switches DCAS support on. You may manually disable DCAS support with the following command line flags\r
  49 in GCC/clang (for MS VC++ compiler DCAS is not supported):\r
  50   - `-DCDS_DISABLE_128BIT_ATOMIC` - for 64bit build\r
  51   - `-DCDS_DISABLE_64BIT_ATOMIC` - for 32bit build\r
  52 \r
  53 **All your projects AND libcds MUST be compiled with the same flags - either with DCAS support or without it.**\r
  54    \r
  55    \r
  56 **Pull request requirements**\r
  57 - Pull-request to *master* branch will be unconditionally rejected\r
  58 - *integration* branch is intended for pull-request. Usually, *integration* branch is the same as *master*\r
  59 - *dev* branch is intended for main developing. Usually, it contains unstable code\r
  60 \r
  61 [![Project stats](https://www.openhub.net/p/khizmax-libcds/widgets/project_thin_badge.gif)](https://www.openhub.net/p/khizmax-libcds)\r
  62 \r
  63 References\r
  64 ----------\r
  65 *Stack*\r
  66   - *TreiberStack*: [1986] R. K. Treiber. Systems programming: Coping with parallelism. Technical Report RJ 5118, IBM Almaden Research Center, April 1986.\r
  67   - Elimination back-off implementation is based on idea from [2004] Danny Hendler, Nir Shavit, Lena Yerushalmi "A Scalable Lock-free Stack Algorithm"\r
  68         [pdf](http://people.csail.mit.edu/shanir/publications/Lock_Free.pdf)\r
  69   - *FCStack* - flat-combining wrapper for *std::stack*\r
  70         \r
  71 *Queue*\r
  72   - *BasketQueue*: [2007] Moshe Hoffman, Ori Shalev, Nir Shavit "The Baskets Queue"\r
  73         [pdf](http://people.csail.mit.edu/shanir/publications/Baskets%20Queue.pdf)\r
  74   - *MSQueue*:\r
  75     * [1998] Maged Michael, Michael Scott "Simple, fast, and practical non-blocking and blocking concurrent queue algorithms"\r
  76         [pdf](http://www.cs.rochester.edu/~scott/papers/1996_PODC_queues.pdf)\r
  77     * [2002] Maged M.Michael "Safe memory reclamation for dynamic lock-free objects using atomic reads and writes"\r
  78         [pdf](http://www.research.ibm.com/people/m/michael/podc-2002.pdf)\r
  79     * [2003] Maged M.Michael "Hazard Pointers: Safe memory reclamation for lock-free objects"\r
  80         [pdf](http://www.research.ibm.com/people/m/michael/ieeetpds-2004.pdf)\r
  81   - *RWQueue*: [1998] Maged Michael, Michael Scott "Simple, fast, and practical non-blocking and blocking concurrent queue algorithms"\r
  82         [pdf](http://www.cs.rochester.edu/~scott/papers/1996_PODC_queues.pdf)\r
  83   - *MoirQueue*: [2000] Simon Doherty, Lindsay Groves, Victor Luchangco, Mark Moir "Formal Verification of a practical lock-free queue algorithm"\r
  84         [pdf](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.87.9954&rep=rep1&type=pdf)\r
  85   - *OptimisticQueue*: [2008] Edya Ladan-Mozes, Nir Shavit "An Optimistic Approach to Lock-Free FIFO Queues"\r
  86         [pdf](https://people.csail.mit.edu/edya/publications/OptimisticFIFOQueue-journal.pdf)\r
  87   - *SegmentedQueue*: [2010] Afek, Korland, Yanovsky "Quasi-Linearizability: relaxed consistency for improved concurrency"\r
  88         [pdf](http://mcg.cs.tau.ac.il/papers/opodis2010-quasi.pdf)\r
  89   - *FCQueue* - flat-combining wrapper for *std::queue*\r
  90   - *VyukovMPMCCycleQueue* Dmitry Vyukov (see http://www.1024cores.net)\r
  91 \r
  92 *Deque*\r
  93   - flat-combining deque based on *stl::deque*\r
  94 \r
  95 *Map, set*\r
  96   - *MichaelHashMap*: [2002] Maged Michael "High performance dynamic lock-free hash tables and list-based sets"\r
  97         [pdf](http://www.research.ibm.com/people/m/michael/spaa-2002.pdf)\r
  98   - *SplitOrderedList*: [2003] Ori Shalev, Nir Shavit "Split-Ordered Lists - Lock-free Resizable Hash Tables"\r
  99         [pdf](http://people.csail.mit.edu/shanir/publications/Split-Ordered_Lists.pdf)\r
 100   - *StripedMap*, *StripedSet*: [2008] Maurice Herlihy, Nir Shavit "The Art of Multiprocessor Programming"\r
 101   - *CuckooMap*, *CuckooSet*: [2008] Maurice Herlihy, Nir Shavit "The Art of Multiprocessor Programming"\r
 102   - *SkipListMap*, *SkipListSet*: [2008] Maurice Herlihy, Nir Shavit "The Art of Multiprocessor Programming"\r
 103   - *FeldmanHashMap*, *FeldmanHashSet*: [2013] Steven Feldman, Pierre LaBorde, Damian Dechev "Concurrent Multi-level Arrays:\r
 104         Wait-free Extensible Hash Maps". Supports **thread-safe bidirectional iterators**\r
 105         [pdf](http://samos-conference.com/Resources_Samos_Websites/Proceedings_Repository_SAMOS/2013/Files/2013-IC-20.pdf)\r
 106         \r
 107 *Ordered single-linked list*\r
 108   - *LazyList*: [2005] Steve Heller, Maurice Herlihy, Victor Luchangco, Mark Moir, William N. Scherer III, and Nir Shavit "A Lazy Concurrent List-Based Set Algorithm"\r
 109         [pdf](http://people.csail.mit.edu/shanir/publications/Lazy_Concurrent.pdf)\r
 110   - *MichaelList*: [2002] Maged Michael "High performance dynamic lock-free hash tables and list-based sets"\r
 111         [pdf](http://www.research.ibm.com/people/m/michael/spaa-2002.pdf)\r
 112 \r
 113 *Priority queue*\r
 114   - *MSPriorityQueue*: [1996] G.Hunt, M.Michael, S. Parthasarathy, M.Scott "An efficient algorithm for concurrent priority queue heaps"\r
 115         [pdf](http://web.cse.ohio-state.edu/dmrl/papers/heap96.pdf)\r
 116 \r
 117 *Tree*\r
 118   - *EllenBinTree*: [2010] F.Ellen, P.Fatourou, E.Ruppert, F.van Breugel "Non-blocking Binary Search Tree"\r
 119         [pdf](http://www.cs.vu.nl/~tcs/cm/faith.pdf)\r
 120   - *BronsonAVLTreeMap* - lock-based fine-grained AVL-tree implementation: \r
 121         [2010] Nathan Bronson, Jared Casper, Hassan Chafi, Kunle Olukotun "A Practical Concurrent Binary Search Tree"\r
 122         [pdf](https://ppl.stanford.edu/papers/ppopp207-bronson.pdf)\r
 123 \r
 124 *SMR*\r
 125   - Hazard Pointers\r
 126     * [2002] Maged M.Michael "Safe memory reclamation for dynamic lock-free objects using atomic reads and writes" \r
 127              [pdf](http://www.research.ibm.com/people/m/michael/podc-2002.pdf)\r
 128     * [2003] Maged M.Michael "Hazard Pointers: Safe memory reclamation for lock-free objects" \r
 129              [pdf](http://www.research.ibm.com/people/m/michael/ieeetpds-2004.pdf)\r
 130     * [2004] Andrei Alexandrescy, Maged Michael "Lock-free Data Structures with Hazard Pointers" \r
 131              [pdf](http://www.researchgate.net/profile/Andrei_Alexandrescu/publication/252573326_Lock-Free_Data_Structures_with_Hazard_Pointers/links/0deec529e7804288fe000000.pdf)\r
 132   - User-space RCU\r
 133     * [2009] M.Desnoyers "Low-Impact Operating System Tracing" PhD Thesis,\r
 134              Chapter 6 "User-Level Implementations of Read-Copy Update"\r
 135              [pdf](http://www.lttng.org/files/thesis/desnoyers-dissertation-2009-12-v27.pdf)\r
 136     * [2011] M.Desnoyers, P.McKenney, A.Stern, M.Dagenias, J.Walpole "User-Level\r
 137              Implementations of Read-Copy Update"\r
 138              [pdf](http://www.dorsal.polymtl.ca/sites/www.dorsal.polymtl.ca/files/publications/desnoyers-ieee-urcu-submitted.pdf)\r
 139 \r
 140 *Flat Combining* technique\r
 141   - [2010] Hendler, Incze, Shavit and Tzafrir "Flat Combining and the Synchronization-Parallelism Tradeoff"\r
 142             [pdf](http://www.cs.bgu.ac.il/~hendlerd/papers/flat-combining.pdf)\r