{"id":13670881,"url":"https://github.com/eBay/Jungle","last_synced_at":"2025-04-27T13:33:07.269Z","repository":{"id":38041206,"uuid":"230492612","full_name":"eBay/Jungle","owner":"eBay","description":"An embedded key-value store library specialized for building state machine and log store","archived":false,"fork":false,"pushed_at":"2025-04-03T22:41:58.000Z","size":1062,"stargazers_count":226,"open_issues_count":5,"forks_count":54,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-03T23:28:01.330Z","etag":null,"topics":["b-tree","embedded-kv","hybrid","key-value-store","logstore","lsm-tree","state-machine"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eBay.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":"2019-12-27T18:09:50.000Z","updated_at":"2025-04-03T22:42:02.000Z","dependencies_parsed_at":"2023-02-01T05:15:44.607Z","dependency_job_id":"d811bd45-75f2-4f15-82a1-42ff45285a51","html_url":"https://github.com/eBay/Jungle","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eBay%2FJungle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eBay%2FJungle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eBay%2FJungle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eBay%2FJungle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eBay","download_url":"https://codeload.github.com/eBay/Jungle/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251145738,"owners_count":21543093,"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":["b-tree","embedded-kv","hybrid","key-value-store","logstore","lsm-tree","state-machine"],"created_at":"2024-08-02T09:00:51.852Z","updated_at":"2025-04-27T13:33:02.248Z","avatar_url":"https://github.com/eBay.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"\n\nJungle\n======\n\n[![build](https://github.com/eBay/Jungle/workflows/build/badge.svg)](https://github.com/eBay/Jungle/actions)\n[![codecov](https://codecov.io/gh/eBay/Jungle/branch/master/graph/badge.svg)](https://codecov.io/gh/eBay/Jungle)\n\n\nEmbedded key-value storage library, based on a combined index of [LSM-tree](https://en.wikipedia.org/wiki/Log-structured_merge-tree) and [copy-on-write (append-only) B+tree](https://www.usenix.org/legacy/events/lsf07/tech/rodeh.pdf). Please refer to our [paper](https://www.usenix.org/conference/hotstorage19/presentation/ahn).\n\nJungle is specialized for building [replicated state machine](https://en.wikipedia.org/wiki/State_machine_replication) of consensus protocols such as [Paxos](https://en.wikipedia.org/wiki/Paxos_(computer_science)) or [Raft](https://raft.github.io/), by providing chronological ordering and lightweight persistent snapshot. It can be also used for building log store.\n\n\nFeatures\n--------\n* Ordered mapping of key and its value on disk (file system). Both key and value are arbitrary length binary.\n* Monotonically increasing sequence number for each key-value modification.\n* Point lookup on both key and sequence number.\n* Range lookup on both key and sequence number, by using iterator:\n    * Snapshot isolation: each individual iterator is a snapshot.\n    * Bi-directional traversal and jump: `prev`, `next`, `gotoBegin`, `gotoEnd`, and `seek`.\n* Lightweight persistent snapshot, based on sequence number:\n    * Nearly no overhead for the creation of a snapshot.\n    * Snapshots are durable; preserved even after process restart.\n* Tunable configurations:\n    * The number of threads for log flushing and compaction.\n    * Custom size ratio between LSM levels.\n    * Compaction factor (please refer to the paper).\n* Log store mode:\n    * Ordered mapping of sequence number and value, eliminating key indexing.\n    * Lightweight log truncation based on sequence number.\n\n### Things we DO NOT (and also WILL NOT) support\n* Secondary indexing, or SQL-like query:\n    * Jungle will not understand the contents of value. Value is just a binary from Jungle's point of view.\n* Server-client style service, or all other network-involving tasks such as replication:\n    * Jungle is a library that should be embedded into your process.\n\n\nBenefits\n--------\nCompared to other widely used LSM-based key-value storage libraries, benefits of Jungle are as follows:\n\n* Smaller write amplification.\n    * Jungle will have 4-5 times less write amplification, while providing the similar level of write performance.\n* Chronological ordering of key-value pairs\n    * Along with persistent logical snapshot, this feature is very useful when you use it as a replicated state machine for Paxos or Raft.\n\n\n\nHow to Build\n------------\n#### 1. Install `cmake`: ####\n* Ubuntu\n```sh\n$ sudo apt-get install cmake\n```\n\n* OSX\n```sh\n$ brew install cmake\n```\n\n#### 2. Build ####\n```sh\njungle$ ./prepare.sh -j8\njungle$ mkdir build\njungle$ cd build\njungle/build$ cmake ../\njungle/build$ make\n```\n\nRun unit tests:\n```\njungle/build$ ./runtests.sh\n```\n\n\nHow to Use\n----------\nPlease refer to [this document](./docs/how_to_use.md).\n\n\nExample Implementation\n-----------------------\nPlease refer to [examples](./examples).\n\n\nSupported Platforms\n-------------------\n* Ubuntu (tested on 14.04, 16.04, and 18.04)\n* Centos (tested on 7)\n* OSX (tested on 10.13 and 10.14)\n\n#### Platforms will be supported in the future\n* Windows\n\n\nContributing to This Project\n----------------------------\nWe welcome contributions. If you find any bugs, potential flaws and edge cases, improvements, new feature suggestions or discussions, please submit issues or pull requests.\n\n\nContact\n-------\n* Jung-Sang Ahn \u003cjungsang.ahn@gmail.com\u003e\n\n\nCoding Convention\n-----------------\n* Recommended not to exceed 90 characters per line.\n* Indent: 4 spaces, K\u0026R (1TBS).\n* Class \u0026 struct name: `UpperCamelCase`.\n* Member function and member variable name: `lowerCamelCase`.\n* Local variable, helper function, and parameter name: `snake_case`.\n\n```C++\nclass MyClass {\npublic:\n    void myFunction(int my_parameter) {\n        int local_var = my_parameter + 1;\n        if (local_var \u003c myVariable) {\n            // ...\n        } else {\n            // ...\n        }\n    }\nprivate:\n    int myVariable;\n};\n\nint helper_function() {\n    return 0;\n}\n```\n\n* Header include order: local to global.\n    1. Header file corresponding to this source file (if applicable).\n    2. Header files in the same project (i.e., Jungle).\n    3. Header files from the other projects.\n    4. C++ system header files.\n    5. C system header files.\n    * Note: alphabetical order within the same category.\n    * Example (`my_file.cc`):\n```C++\n#include \"my_file.h\"            // Corresponding header file.\n\n#include \"table_file.h\"         // Header files in the same project.\n#include \"table_helper.h\"\n\n#include \"forestdb.h\"           // Header files from the other projects.\n\n#include \u003ccassert\u003e              // C++ header files.\n#include \u003ciostream\u003e\n#include \u003cvector\u003e\n\n#include \u003csys/stat.h\u003e           // C header files.\n#include \u003csys/types.h\u003e\n#include \u003cunistd.h\u003e\n```\n\nLicense Information\n--------------------\nCopyright 2017-present eBay Inc.\n\nLicensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with the License. You may obtain a copy of the License at\n\nhttps://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.\n\n\n3rd Party Code\n--------------\n1. URL: https://github.com/couchbase/forestdb\u003cbr\u003e\nLicense: https://github.com/couchbase/forestdb/blob/master/LICENSE\u003cbr\u003e\nOriginally licensed under the Apache 2.0 license.\n\n2. URL: https://github.com/stbrumme/crc32\u003cbr\u003e\nOriginal Copyright 2011-2016 Stephan Brumme\u003cbr\u003e\nSee Original ZLib License: https://github.com/stbrumme/crc32/blob/master/LICENSE\n\n3. URL: https://github.com/greensky00/simple_logger\u003cbr\u003e\nLicense: https://github.com/greensky00/simple_logger/blob/master/LICENSE\u003cbr\u003e\nOriginally licensed under the MIT license.\n\n4. URL: https://github.com/greensky00/testsuite\u003cbr\u003e\nLicense: https://github.com/greensky00/testsuite/blob/master/LICENSE\u003cbr\u003e\nOriginally licensed under the MIT license.\n\n5. URL: https://github.com/greensky00/latency-collector\u003cbr\u003e\nLicense: https://github.com/greensky00/latency-collector/blob/master/LICENSE\u003cbr\u003e\nOriginally licensed under the MIT license.\n\n6. URL: https://github.com/eriwen/lcov-to-cobertura-xml/blob/master/lcov_cobertura/lcov_cobertura.py\u003cbr\u003e\nLicense: https://github.com/eriwen/lcov-to-cobertura-xml/blob/master/LICENSE\u003cbr\u003e\nCopyright 2011-2012 Eric Wendelin\u003cbr\u003e\nOriginally licensed under the Apache 2.0 license.\n\n7. URL: https://github.com/bilke/cmake-modules\u003cbr\u003e\nLicense: https://github.com/bilke/cmake-modules/blob/master/LICENSE_1_0.txt\u003cbr\u003e\nCopyright 2012-2017 Lars Bilke\u003cbr\u003e\nOriginally licensed under the BSD license.\n\n8. URL: https://github.com/aappleby/smhasher/tree/master/src\u003cbr\u003e\nCopyright 2016 Austin Appleby\u003cbr\u003e\nOriginally licensed under the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FeBay%2FJungle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FeBay%2FJungle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FeBay%2FJungle/lists"}