{"id":13424438,"url":"https://github.com/mpoeter/xenium","last_synced_at":"2025-05-15T15:03:32.651Z","repository":{"id":43175135,"uuid":"146625651","full_name":"mpoeter/xenium","owner":"mpoeter","description":"A C++ library providing various concurrent data structures and reclamation schemes.","archived":false,"fork":false,"pushed_at":"2025-03-25T10:50:49.000Z","size":1438,"stargazers_count":569,"open_issues_count":14,"forks_count":57,"subscribers_count":25,"default_branch":"main","last_synced_at":"2025-03-31T20:06:12.586Z","etag":null,"topics":["concurrency","cpp","cpp17","debra","epoch-based-reclamation","hazard-era","hazard-pointer","lock-free","reclamation-schemes"],"latest_commit_sha":null,"homepage":"https://mpoeter.github.io/xenium/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mpoeter.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-29T16:07:43.000Z","updated_at":"2025-03-29T12:32:21.000Z","dependencies_parsed_at":"2023-11-23T14:23:45.997Z","dependency_job_id":"6dd398b3-9302-4c37-af4d-dbf3cda937e7","html_url":"https://github.com/mpoeter/xenium","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mpoeter%2Fxenium","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mpoeter%2Fxenium/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mpoeter%2Fxenium/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mpoeter%2Fxenium/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mpoeter","download_url":"https://codeload.github.com/mpoeter/xenium/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247730068,"owners_count":20986404,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["concurrency","cpp","cpp17","debra","epoch-based-reclamation","hazard-era","hazard-pointer","lock-free","reclamation-schemes"],"created_at":"2024-07-31T00:00:54.310Z","updated_at":"2025-04-07T21:09:18.710Z","avatar_url":"https://github.com/mpoeter.png","language":"C++","readme":"# xenium\n\n[![Build Status](https://dl.circleci.com/status-badge/img/gh/mpoeter/xenium/tree/master.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/mpoeter/xenium/tree/master)\n[![MIT Licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![Documentation](https://img.shields.io/badge/docs-doxygen-purple.svg)](https://mpoeter.github.io/xenium)\n\nxenium is a header-only library that provides a collection of concurrent data structures\nand memory reclamation algorithms. The data structures are parameterized so that they can\nbe used with various reclamation schemes (similar to how the STL allows customization of\nallocators).\n\n * header only\n * highly customizable\n * no initialization code needed\n * supports dynamic number of threads (no fixed compile time specification)\n\nThe [documentation](https://mpoeter.github.io/xenium) provides more details.\n\nThis project is based on my previous work in https://github.com/mpoeter/emr\n\n# Usage Example\n\n```cpp\n#include \u003cxenium/ramalhete_queue.hpp\u003e\n#include \u003cxenium/reclamation/epoch_based.hpp\u003e\n\nstruct msg { ... };\n\nxenium::ramalhete_queue\u003c\n  std::unique_ptr\u003cmsg\u003e,\n  xenium::policy::reclaimer\u003cxenium::reclamation::epoch_based\u003c\u003e\u003e,\n  xenium::policy::entries_per_node\u003c2048\u003e\n\u003e queue;\n\nqueue.push(std::make_unique\u003cmsg\u003e());\n\nstd::unique_ptr\u003cmsg\u003e data;\nif (queue.try_pop(data)) {\n    // do something with data\n}\n```\n\n## Data Structures\nAt the moment the number of provided data structures is rather small since the focus so far\nwas on the reclamation schemes. However, the plan is to add several more data structures in\nthe near future.\n\n* `michael_scott_queue` - an unbounded lock-free multi-producer/multi-consumer queue proposed by\nMichael and Scott \\[[MS96](#ref-michael-1996)\\].\n* `ramalhete_queue` - a fast unbounded lock-free multi-producer/multi-consumer queue proposed by\nRamalhete \\[[Ram16](#ref-ramalhete-2016)\\].\n* `vyukov_bounded_queue` - a bounded multi-producer/multi-consumer FIFO queue based on the version proposed by Vyukov \\[[Vyu10 ](#ref-vyukov-2010)\\].\n* `kirsch_kfifo_queue` - an unbounded multi-producer/multi-consumer k-FIFO queue proposed by Kirsch et al. \\[[KLP13](#ref-kirsch-2013)\\].\n* `kirsch_bounded_kfifo_queue` - a bounded multi-producer/multi-consumer k-FIFO queue proposed by Kirsch et al. \\[[KLP13](#ref-kirsch-2013)\\].\n* `nikolaev_queue` - an unbounded multi-producer/multi-consumer queue proposed by Nikolaev \\[[Nik19](#ref-nikolaev-2019)\\].\n* `nikolaev_bounded_queue` - a bounded multi-producer/multi-consumer queue proposed by Nikolaev \\[[Nik19](#ref-nikolaev-2019)\\].\n* `harris_michael_list_based_set` - a lock-free container that contains a sorted set of unique objects.\nThis data structure is based on the solution proposed by Michael \\[[Mic02](#ref-michael-2002)\\] which builds\nupon the original proposal by Harris \\[[Har01](#ref-harris-2001)\\].\n* `harris_michael_hash_map` - a lock-free hash-map based on the solution proposed by Michael\n\\[[Mic02](#ref-michael-2002)\\] which builds upon the original proposal by Harris \\[[Har01](#ref-harris-2001)\\].\n* `chase_work_stealing_deque` - a work stealing deque based on the proposal by\nChase and Lev \\[[CL05](#ref-chase-2005)\\].\n* `vyukov_hash_map` - a concurrent hash-map that uses fine grained locking for update operations.\nThis implementation is heavily inspired by the version proposed by Vyukov \\[[Vyu08](#ref-vyukov-2008)\\].\n* `left_right` - a generic implementation of the LeftRight algorithm proposed by Ramalhete and Correia\n\\[[RC15](#ref-ramalhete-2015)\\].\n* `seqlock` - an implementation of the sequence lock (also often referred to as \"sequential lock\").\n\n## Reclamation Schemes\n\nThe implementation of the reclamation schemes is based on an adapted version of the interface\nproposed by Robison \\[[Rob13](#ref-robison-2013)\\].\n\nThe following reclamation schemes are implemented:\n* `lock_free_ref_count` \\[[Val95](#ref-valois-1995), [MS95](#ref-michael-1995)\\]\n* `hazard_pointer` \\[[Mic04](#ref-michael-2004)\\]\n* `hazard_eras` \\[[RC17](#ref-ramalhete-2017)\\]\n* `quiescent_state_based`\n* `generic_epoch_based` - this is a generalized epoch based reclaimer that can be configured in several\nways. For simplicity, the following aliases are predefined for the corresponding configurations.\n  * `epoch_based` \\[[Fra04](#ref-fraser-2004)\\]\n  * `new_epoch_based` \\[[HMBW07](#ref-hart-2007)\\]\n  * `debra` \\[[Bro15](#ref-brown-2015)\\]\n* `stamp_it` \\[[PT18a](#ref-pöter-2018), [PT18b](#ref-pöter-2018-tr)\\]\n\n## Building\n\nxenium is a header only library, so in order to use it, it is sufficient to include the xenium folder\nin your list of include directories. No other 3rd party libraries are required. However, the implementation\nuses C++17 features, so a compiler with sufficient C++17 support is required. The following compilers are\nused in the CI builds and are therefore known to be supported:\n  * gcc9\n  * clang10\n  * Visual Studio 2019\n\nThe unit test require `googletest` and the benchmarks require `taocpp/json` and `taocpp/config`. These\ndependencies are included as submodules, so the unit tests and/or the benchmarks can be built as follows:\n```\ngit clone https://github.com/mpoeter/xenium.git \u0026\u0026 cd xenium\ngit submodule update --init --recursive\nmkdir build \u0026\u0026 cd build\ncmake ..\nmake gtest\nmake benchmark\n```\n\n\n### References\n\n\u003ctable style=\"border:0px\"\u003e\n\u003ctr\u003e\n    \u003ctd valign=\"top\"\u003e\u003ca name=\"ref-brown-2015\"\u003e\u003c/a\u003e[Bro15]\u003c/td\u003e\n    \u003ctd\u003eTrevor Alexander Brown.\n    \u003ca href=http://www.cs.utoronto.ca/~tabrown/debra/paper.podc15.pdf\u003e\n    Reclaiming memory for lock-free data structures: There has to be a better way\u003c/a\u003e.\n    In \u003ci\u003eProceedings of the 2015 ACM Symposium on Principles of Distributed Computing (PODC)\u003c/i\u003e,\n    pages 261–270. ACM, 2015.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n    \u003ctd valign=\"top\"\u003e\u003ca name=\"ref-chase-2005\"\u003e\u003c/a\u003e[CL05]\u003c/td\u003e\n    \u003ctd\u003eDavid Chase and Yossi Lev.\n    \u003ca href=https://www.dre.vanderbilt.edu/~schmidt/PDF/work-stealing-dequeue.pdf\u003e\n    Dynamic circular work-stealing deque\u003c/a\u003e.\n    In \u003ci\u003eProceedings of the 17th Annual ACM Symposium on Parallelism in Algorithms and Architectures (SPAA)\u003c/i\u003e,\n    pages 21–28. ACM, 2005.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n    \u003ctd valign=\"top\"\u003e\u003ca name=\"ref-fraser-2004\"\u003e\u003c/a\u003e[Fra04]\u003c/td\u003e\n    \u003ctd\u003eKeir Fraser.\n    \u003ca href=https://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-579.pdf\u003e\n    \u003ci\u003ePractical lock-freedom\u003c/i\u003e\u003c/a\u003e.\n    PhD thesis, University of Cambridge Computer Laboratory, 2004.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n    \u003ctd valign=\"top\"\u003e\u003ca name=\"ref-harris-2001\"\u003e\u003c/a\u003e[Har01]\u003c/td\u003e\n    \u003ctd\u003eTimothy L. Harris.\n    \u003ca href=https://www.cl.cam.ac.uk/research/srg/netos/papers/2001-caslists.pdf\u003e\n    A pragmatic implementation of non-blocking linked-lists\u003c/a\u003e.\n    In \u003ci\u003eProceedings of the 15th International Conference on Distributed Computing (DISC)\u003c/i\u003e,\n    pages 300–314. Springer-Verlag, 2001.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n    \u003ctd valign=\"top\"\u003e\u003ca name=\"ref-hart-2007\"\u003e\u003c/a\u003e[HMBW07]\u003c/td\u003e\n    \u003ctd\u003eThomas E. Hart, Paul E. McKenney, Angela Demke Brown, and Jonathan Walpole.\n    \u003ca href=http://csng.cs.toronto.edu/publication_files/0000/0159/jpdc07.pdf\u003e\n    Performance of memory reclamation for lockless synchronization\u003c/a\u003e.\n    Journal of Parallel and Distributed Computing, 67(12):1270–1285, 2007.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n    \u003ctd valign=\"top\"\u003e\u003ca name=\"ref-kirsch-2013\"\u003e\u003c/a\u003e[KLP13]\u003c/td\u003e\n    \u003ctd\u003eChristoph Kirsch, Michael Lippautz, and Hannes Payer.\n    \u003ca href=\"http://www.cs.uni-salzburg.at/~ck/content/publications/conferences/PaCT13-FastScalableQueues.pdf\"\u003e\n    Fast and scalable, lock-free k-FIFO queues\u003c/a\u003e.\n    In \u003ci\u003eProceedings of the International Conference on Parallel Computing Technologies (PaCT)\u003c/i\u003e, pages 208–223, Springer-Verlag, 2013.\n\u003c/tr\u003e\n\u003ctr\u003e\n    \u003ctd valign=\"top\"\u003e\u003ca name=\"ref-michael-2002\"\u003e\u003c/a\u003e[Mic02]\u003c/td\u003e\n    \u003ctd\u003eMaged M. Michael.\n    \u003ca href=https://www.liblfds.org/downloads/white%20papers/%5BHash%5D%20-%20%5BMichael%5D%20-%20High%20Performance%20Dynamic%20Lock-Free%20Hash%20Tables%20and%20List-Based%20Sets.pdf\u003e\n    High performance dynamic lock-free hash tables and list-based sets\u003c/a\u003e.\n    In \u003ci\u003eProceedings of the 14th Annual ACM Symposium on Parallel Algorithms and Architectures\n    (SPAA)\u003c/i\u003e, pages 73–82. ACM, 2002.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n    \u003ctd valign=\"top\"\u003e\u003ca name=\"ref-michael-2004\"\u003e\u003c/a\u003e[Mic04]\u003c/td\u003e\n    \u003ctd\u003eMaged M. Michael.\n    \u003ca href=http://www.cs.otago.ac.nz/cosc440/readings/hazard-pointers.pdf\u003e\n    Hazard pointers: Safe memory reclamation for lock-free objects\u003c/a\u003e.\n    IEEE Transactions on Parallel and Distributed Systems, 15(6):491–504, 2004.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n    \u003ctd valign=\"top\"\u003e\u003ca name=\"ref-michael-1995\"\u003e\u003c/a\u003e[MS95]\u003c/td\u003e\n    \u003ctd\u003eMaged M. Michael and Michael L. Scott.\n    \u003ca href=https://pdfs.semanticscholar.org/cec0/ad7b0fc2d4d6ba45c6212d36217df1ff2bf2.pdf\u003e\n    Correction of a memory management method for lock-free data structures\u003c/a\u003e.\n    Technical report, University of Rochester, 1995.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n    \u003ctd valign=\"top\"\u003e\u003ca name=\"ref-michael-1996\"\u003e\u003c/a\u003e[MS96]\u003c/td\u003e\n    \u003ctd\u003eMaged M. Michael and Michael L. Scott.\n    \u003ca href=http://www.cs.rochester.edu/~scott/papers/1996_PODC_queues.pdf\u003e\n    Simple, fast, and practical non-blocking and blocking concurrent queue algorithms\u003c/a\u003e.\n    In \u003ci\u003eProceedings of the 15th Annual ACM Symposium on Principles of Distributed Computing (PODC)\u003c/i\u003e,\n    pages 267–275. ACM, 1996.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n    \u003ctd valign=\"top\"\u003e\u003ca name=\"ref-nikolaev-2019\"\u003e\u003c/a\u003e[Nik19]\u003c/td\u003e\n    \u003ctd\u003eRuslan Nikolaev\n    \u003ca href=\"http://drops.dagstuhl.de/opus/volltexte/2019/11335/pdf/LIPIcs-DISC-2019-28.pdf\"\u003e\n    A scalable, portable, and memory-efficient lock-free fifo queue\u003c/a\u003e. In \u003ci\u003eProceedings of the 33rd\n    International Symposium on Distributed Computing (DISC)\u003c/i\u003e, 2019.\n\u003c/tr\u003e\n\u003ctr\u003e\n    \u003ctd valign=\"top\"\u003e\u003ca name=\"ref-pöter-2018\"\u003e\u003c/a\u003e[PT18a]\u003c/td\u003e\n    \u003ctd\u003eManuel Pöter and Jesper Larsson Träff.\n    Brief announcement: Stamp-it, a more thread-efficient, concurrent memory reclamation scheme in the C++ memory model.\n    In \u003ci\u003eProceedings of the 30th Annual ACM Symposium on Parallelism in Algorithms and Architectures (SPAA)\u003c/i\u003e,\n    pages 355–358. ACM, 2018.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n    \u003ctd valign=\"top\"\u003e\u003ca name=\"ref-pöter-2018-tr\"\u003e\u003c/a\u003e[PT18b]\u003c/td\u003e\n    \u003ctd\u003eManuel Pöter and Jesper Larsson Träff.\n    \u003ca href=https://arxiv.org/pdf/1805.08639.pdf\u003e\n    Stamp-it, a more thread-efficient, concurrent memory reclamation scheme in the C++ memory model\u003c/a\u003e.\n    Technical report, 2018.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n    \u003ctd valign=\"top\"\u003e\u003ca name=\"ref-ramalhete-2016\"\u003e\u003c/a\u003e[Ram16]\u003c/td\u003e\n    \u003ctd\u003ePedro Ramalhete.\n    \u003ca href=http://concurrencyfreaks.blogspot.com/2016/11/faaarrayqueue-mpmc-lock-free-queue-part.html\u003e\n    FAAArrayQueue - MPMC lock-free queue (part 4 of 4)\u003c/a\u003e.\n    Blog, November 2016.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n    \u003ctd valign=\"top\"\u003e\u003ca name=\"ref-ramalhete-2015\"\u003e\u003c/a\u003e[RC15]\u003c/td\u003e\n    \u003ctd\u003ePedro Ramalhete and Andreia Correia.\n    \u003ca href=https://github.com/pramalhe/ConcurrencyFreaks/blob/master/papers/left-right-2014.pdf\u003e\n    Left-Right - A Concurrency Control Technique with Wait-Free Population Oblivious Reads\u003c/a\u003e.\n    October 2015\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n    \u003ctd valign=\"top\"\u003e\u003ca name=\"ref-ramalhete-2017\"\u003e\u003c/a\u003e[RC17]\u003c/td\u003e\n    \u003ctd\u003ePedro Ramalhete and Andreia Correia.\n    \u003ca href=https://github.com/pramalhe/ConcurrencyFreaks/blob/master/papers/hazarderas-2017.pdf\u003e\n    Brief announcement: Hazard eras - non-blocking memory reclamation\u003c/a\u003e.\n    In \u003ci\u003eProceedings of the 29th Annual ACM Symposium on Parallelism in Algorithms and Architectures (SPAA)\u003c/i\u003e,\n    pages 367–369. ACM, 2017.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n    \u003ctd valign=\"top\"\u003e\u003ca name=\"ref-robison-2013\"\u003e\u003c/a\u003e[Rob13]\u003c/td\u003e\n    \u003ctd\u003eArch D. Robison.\n    \u003ca href=http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3712.pdf\u003e\n    Policy-based design for safe destruction in concurrent containers\u003c/a\u003e.\n    C++ standards committee paper, 2013.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n    \u003ctd valign=\"top\"\u003e\u003ca name=\"ref-valois-1995\"\u003e\u003c/a\u003e[Val95]\u003c/td\u003e\n    \u003ctd\u003eJohn D. Valois. \u003ci\u003eLock-Free Data Structures\u003c/i\u003e.\n    PhD thesis, Rensselaer Polytechnic Institute, 1995.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n    \u003ctd valign=\"top\"\u003e\u003ca name=\"ref-vyukov-2008\"\u003e\u003c/a\u003e[Vyu08]\u003c/td\u003e\n    \u003ctd\u003eDmitry Vyukov.\n    \u003ca href=https://groups.google.com/forum/#!topic/lock-free/qCYGGkrwbcA\u003e\n    Scalable hash map\u003c/a\u003e. Google Groups posting, 2008.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n    \u003ctd valign=\"top\"\u003e\u003ca name=\"ref-vyukov-2010\"\u003e\u003c/a\u003e[Vyu10]\u003c/td\u003e\n    \u003ctd\u003eDmitry Vyukov.\n    \u003ca href=https://groups.google.com/forum/#!topic/lock-free/-bqYlfbQmH0\u003e\n    Simple and efficient bounded MPMC queue\u003c/a\u003e. Google Groups posting, 2010.\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n","funding_links":[],"categories":["C++","Libraries","Software","Concurrency"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmpoeter%2Fxenium","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmpoeter%2Fxenium","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmpoeter%2Fxenium/lists"}