{"id":13731539,"url":"https://github.com/microsoft/Kuku","last_synced_at":"2025-05-08T04:34:32.033Z","repository":{"id":64004866,"uuid":"215391541","full_name":"microsoft/Kuku","owner":"microsoft","description":"Kuku is a compact and convenient cuckoo hashing library written in C++.","archived":false,"fork":false,"pushed_at":"2024-07-23T17:41:49.000Z","size":211,"stargazers_count":67,"open_issues_count":2,"forks_count":17,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-07T23:46:59.501Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/microsoft.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-15T20:34:15.000Z","updated_at":"2025-04-11T01:30:38.000Z","dependencies_parsed_at":"2024-07-23T20:26:37.698Z","dependency_job_id":"a46e76fd-664a-4e66-93bf-054b3a6a637f","html_url":"https://github.com/microsoft/Kuku","commit_stats":{"total_commits":108,"total_committers":8,"mean_commits":13.5,"dds":0.4814814814814815,"last_synced_commit":"b1f26f99cc9dd85b67b41c57e7a7c24a46164d60"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2FKuku","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2FKuku/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2FKuku/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2FKuku/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microsoft","download_url":"https://codeload.github.com/microsoft/Kuku/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253001260,"owners_count":21838498,"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":[],"created_at":"2024-08-03T02:01:32.289Z","updated_at":"2025-05-08T04:34:32.016Z","avatar_url":"https://github.com/microsoft.png","language":"C#","funding_links":[],"categories":["Maths"],"sub_categories":[],"readme":"# Kuku\n\nKuku is a simple open-source ([MIT licensed](LICENSE)) cuckoo hashing library developed by the Cryptography and Privacy Research Group at Microsoft.\nKuku is written in modern standard C++ and has no external dependencies, making it easy to compile and run in many different environments.\n\n## Contents\n- [Getting Started](#getting-started)\n  - [Cuckoo Hashing](#cuckoo-hashing)\n  - [Kuku](#kuku-1)\n  - [Installing from NuGet Package](#installing-from-nuget-package-windows-linux-macos)\n- [Building Kuku Manually](#building-kuku-manually)\n  - [Building C++ Components](#building-c-components)\n    - [Building Kuku](#building-kuku)\n    - [Installing Kuku](#installing-kuku)\n    - [Building and Installing on Windows](#building-and-installing-on-windows)\n    - [CMake Options](#cmake-options)\n    - [Linking with Kuku through CMake](#linking-with-kuku-through-cmake)\n  - [Building .NET Components](#building-net-components)\n    - [Windows, Linux, and macOS](#windows-linux-and-macos)\n    - [Using Kuku for .NET](#using-kuku-for-net)\n    - [Building Your Own NuGet Package](#building-your-own-nuget-package)\n- [Using Kuku](#using-kuku)\n- [Contributing](#contributing)\n\n## Getting Started\n\n### Cuckoo Hashing\n\n[Cuckoo hashing](https://en.wikipedia.org/wiki/Cuckoo_hashing) is a hashing technique that can achieve very high fill rates, and in particular create efficient hash tables with a single item per bin.\nThis is achieved by using multiple (often 2, 3, or 4) different hash functions as follows:\n1. Denote the hash functions `H_1`, `H_2`, ..., `H_k`.\n1. When an item `X` is to be inserted, choose one of the hash functions, `H_j`, and\ncheck whether the corresponding bin is empty.\nIf it is empty, insert `X` in the bin denoted by `H_j(X)`, and return `true`.\nOtherwise, remove the existing value, `Y`, from the bin denoted by `H_j(X)`, and insert X in its place.\nRepeat the process for the item `Y`.\n1. If the process fails to terminate after a pre-determined number of attempts,\nplace the leftover item in a stash of a pre-determined maximum size, and return `true`.\n1. If the stash had already reached its maximum size, store the leftover item into\na known location and return `false`.\n\nTo check whether an item `Z` is in the hash table, it is necessary to check all possible locations, i.e.,  `H_1(Z)`, `H_2(Z)`, ..., `H_k(Z)` for its presence, as well as the stash.\nIt is not necessary to use a stash at all, in which case the stash would have size zero and obviously would not need to be checked.\n\n### Kuku\n\nKuku is a minimalistic library that enables a certain variant of cuckoo hashing, as described above.\nIt uses [tabulation hashing](https://en.wikipedia.org/wiki/Tabulation_hashing) for the hash functions.\nThe item length in Kuku is exactly 128 bits and cannot be increased; however, longer items can always be hashed to 128 bits using some other hash function that accepts arbitrary length inputs, and the outputs can subsequently be used in Kuku.\n\n### Installing from NuGet Package (Windows, Linux, macOS)\n\nFor .NET developers the easiest way of installing Kuku is by using the multiplatform NuGet package available at [NuGet.org](https://www.nuget.org/packages/Microsoft.Research.Kuku).\nSimply add this package into your .NET project as a dependency and you are ready to go.\n\n## Building Kuku Manually\n\n### Building C++ Components\n\nOn all platforms Kuku is built with CMake.\nWe recommend using out-of-source build although in-source build works.\nBelow we give instructions for how to configure, build, and install Kuku either globally (system-wide), or locally (for a single user).\nA global install requires elevated (root or administrator) privileges.\n\n#### Building Kuku\n\nWe assume that Kuku has been cloned into a directory called `Kuku` and all commands presented below are assumed to be executed in the directory `Kuku`.\n\nYou can build the Kuku library (out-of-source) for your machine by executing the following commands:\n\n```PowerShell\ncmake -S . -B build\ncmake --build build\n```\n\nAfter the build completes, the output binaries can be found in `build/lib/` and `build/bin/` directories.\n\n#### Installing Kuku\n\nIf you have root access to the system you can install Kuku globally as follows:\n\n```PowerShell\ncmake -S . -B build\ncmake --build build\nsudo cmake --install build\n```\n\nTo instead install Kuku locally, e.g., to `~/mylibs/`, do the following:\n\n```PowerShell\ncmake -S . -B build -DCMAKE_INSTALL_PREFIX=~/mylibs\ncmake --build build\nsudo cmake --install build\n```\n\n#### Building and Installing on Windows\n\nOn Windows the same scripts above work in a developer command prompt for Visual Studio using either the Ninja or \"Visual Studio 16 2019\" generators.\n\nWhen using the Ninja generator, please use the appropriate command prompt depending on the platform you want to build for. If you want to build for x64, please use the **x64 Native Tools Command Prompt for Visual Studio 2019** command prompt to configure and build the library. If you want to build for x86, please use the **x86 Native Tools Command Prompt for Visual Studio 2019** command prompt to configure and build the library. To build using Ninja, type\n\n```PowerShell\ncmake -S . -B build -G Ninja\ncmake --build build\n```\n\nWhen using the \"Visual Studio 16 2019\" generator you can use the **Developer Command Prompt for VS 2019** command prompt to configure and build the library. By default the generated platform will be x64. You can specify the desired platform using the architecture flag `-A \u003cx64|Win32\u003e` and the desired configuration using `--config \u003cDebug|Release\u003e`.\n\n```PowerShell\n# Generate and build for x64 in Release mode\ncmake -S . -B build -G \"Visual Studio 16 2019\" -A x64\ncmake --build build --config Release\n```\n```PowerShell\n# Generate and build for x86 in Release mode\ncmake -S . -B build -G \"Visual Studio 16 2019\" -A Win32\ncmake --build build --config Release\n```\n\nInstalling the library in Windows works as well. Instead of using the `sudo` command, however, you need to run `cmake --install build` from a command prompt with Administrator permissions. Files will be installed by default to `C:\\Program Files (x86)\\Kuku`.\n\nVisual Studio 2019 provides support for CMake-based projects. You can select the menu option `File / Open / Folder...` and navigate to the folder where the Kuku repository is located. After opening the folder, Visual Studio will detect that this is a CMake-based project and will enable the menu command `Project / CMake settings for Kuku`. This will open the CMake settings editor that provides a user interface where you can create different configurations and set different CMake options.\n\nAfter the build completes, the output static library `kuku-\u003cversion\u003e.lib` can be found in `build\\lib\\` or `build\\lib\\Release\\`.\nWhen linking with applications, you need to add `src\\` (full path) as an include directory to locate the Kuku header files, or use CMake as is explained in [Linking with Kuku through CMake](#linking-with-kuku-through-cmake).\n\n#### CMake Options\n\nThe following options can be used with CMake to configure the build. The default value for each option is denoted with boldface in the **Values** column.\n\n| CMake option        | Values                                                       | Information                                                                                                                                                                                            |\n| ------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| CMAKE_BUILD_TYPE    | **Release**\u003c/br\u003eDebug\u003c/br\u003eRelWithDebInfo\u003c/br\u003eMinSizeRel\u003c/br\u003e | `Debug` and `MinSizeRel` have worse run-time performance. `Debug` inserts additional assertion code. Set to `Release` unless you are developing Kuku itself or debugging some complex issue. |\n| KUKU_BUILD_EXAMPLES | ON / **OFF**                                                 | Build the C++ examples in [examples](examples).                                                                                                                                          |\n| KUKU_BUILD_TESTS    | ON / **OFF**                                                 | Build the tests to check that Kuku works correctly.                                                                                                                                          |\n| BUILD_SHARED_LIBS   | ON / **OFF**                                                 | Set to `ON` to build a shared library instead of a static library. Not supported in Windows.                                                                                                           |\n| KUKU_BUILD_KUKU_C   | ON / **OFF**                                                 | Build the C wrapper library Kuku_C. This is used by the C# wrapper and most users should have no reason to build it.                                                                                   |\n\nAs usual, these options can be passed to CMake with the `-D` flag.\nFor example, one could run\n```PowerShell\ncmake -S . -B build -DKUKU_BUILD_EXAMPLES=ON\n```\nto configure a release build of a static Kuku library and also build the examples.\n\n#### Linking with Kuku through CMake\n\nIt is very easy to link your own applications and libraries with Kuku if you use CMake.\nSimply add the following to your `CMakeLists.txt`:\n\n```PowerShell\nfind_package(Kuku 2.1 REQUIRED)\ntarget_link_libraries(\u003cyour target\u003e Kuku::kuku)\n```\n\nIf Kuku was installed globally, the above `find_package` command will likely find the library automatically.\nTo link with a Kuku installed locally, e.g., installed in `~/mylibs` as described above, you may need to tell CMake where to look for Kuku when you configure your application by running:\n\n```PowerShell\ncd \u003cdirectory containing your CMakeLists.txt\u003e\ncmake . -DCMAKE_PREFIX_PATH=~/mylibs\n```\n\nIf Kuku was installed using a package manager like vcpkg or Homebrew, please refer to their documentation for how to link with the installed library. For example, vcpkg requires you to specify the vcpkg CMake toolchain file when configuring your project.\n\n### Building .NET Components\n\nKuku provides a .NET Standard library that wraps the functionality in Kuku for use in .NET development.\nUsing the existing [NuGet package](https://www.nuget.org/packages/Microsoft.Research.Kuku) is highly recommended, unless development of Kuku or building a custom NuGet package is intended.\nPrior to building .NET components, the C wrapper library Kuku_C must be built following [Building C++ Components](#building-c-components).\nThe Kuku_C library is meant to be used only by the .NET library, not by end-users.\n\n**Note**: Kuku_C and the .NET library only support 64-bit platforms.\n\n#### Windows, Linux, and macOS\n\nFor compiling .NET code you will need to install a [.NET Core SDK (\u003e= 3.1)](https://dotnet.microsoft.com/download).\nBuilding the Kuku_C library with CMake will generate project files for the .NET wrapper library, examples, and unit tests.\nThe Kuku_C library must be discoverable when running a .NET application, e.g., be present in the same directory as your executable, which is taken care of by the .NET examples and tests project files.\nRun the following scripts to build each project:\n\n```PowerShell\ndotnet build dotnet/src --configuration \u003cDebug|Release\u003e # Build .NET wrapper library\ndotnet test dotnet/tests # Build and run .NET unit tests\ndotnet run -p dotnet/examples # Build and run .NET examples\n```\n\nYou can use `--configuration \u003cDebug|Release\u003e` to run `Debug` or `Release` examples and unit tests.\nYou can use `--verbosity detailed` to print the list of unit tests that are being run.\n\nOn Windows, you can also use the Microsoft Visual Studio 2019 solution file `dotnet/KukuNet.sln` to build all three projects.\n\n#### Using Kuku for .NET\n\nTo use Kuku for .NET in your own application you need to:\n\n1. Add a reference in your project to `KukuNet.dll`;\n1. Ensure the native shared library is available for your application when run.\nThe easiest way to ensure this is to copy the native shared library to the same directory where your application's executable is located.\n\n#### Building Your Own NuGet Package\n\nYou can build your own NuGet package for Kuku by following the instructions in [NUGET.md](dotnet/nuget/NUGET.md).\n\n## Using Kuku\n\n### C++\nThe cuckoo hash table is represented by an instance of the `KukuTable` class. The\nconstructor of `KukuTable` takes as input the size of the hash table (`table_size`),\nthe size of the stash (`stash_size`), the number of hash functions (`loc_func_count`),\na seed for the hash functions (`loc_func_seed`), the number of iterations allowed in\nthe insertion process, and a value the hash table should contain to signal an empty\nslot (`empty_item`). The hash tables item are restricted to 128-bit integer data types\n(`item_type`). These can be created from a pair of 64-bit integers using the `make_item`\nfunction.\n\nOnce the table has been created, items can be inserted using the member function `insert`.\nItems can be queried with the member function `query`, which returns a `QueryResult`\nobject. The `QueryResult` contains information about the location in the `KukuTable` where\nthe queried item was found, as well as the hash function that was used to eventually insert\nit. `QueryResult` has an `operator bool()` defined which returns whether the queried item\nwas found in the hash table.\n\nIf Kuku fails to insert an item to the table or to the stash, the `insert` function will\nreturn false, and a leftover item will be stored in a member variable that can be read with\n`leftover_item()`. The same item cannot be inserted multiple times: `insert` will return\n`false` in this case.\n\n### .NET\n\nMuch like in the native library, the cuckoo hash table is represented by an instance of the\n`KukuTable` class. The constructor of `KukuTable` takes as input a set of parameters,\ndefined by the `KukuTableParameters` class. The parameters contain the table size\n`(TableSize`), the size of the stash (`StashSize`), the number of hash functions\n(`LocFuncCount`), a seed for the hash functions (`LocFuncSeed`), the number of iterations\nallowed in the insertion process, and a value the hash table should contain to signal\nan empty slot (`EmptyItem`). The hash tables items are restricted to 128-bit integer data\ntypes. These can be created from an array of size 2 of 64-bit integers by instantiating\nthe `Item` class and setting its `Data` property with a `ulong` array of size 2.\n\nOnce the table has been created, items can be inserted using the member function `Insert`.\nItems can be queried with the member function `Query`, which returns a `QueryResult`\nobject. The `QueryResult` contains information about whether the queried item was\nfound in the hash table, the location where it was found, as well as the hash function that\nwas used to eventually insert it.\n\nIf `KukuTable.Insert` fails to insert an item to the table or to the stash, it will\nreturn `false`, and a leftover item will be stored in a member variable that can be read\nwith `KukuTable.LastInsertFailItem()`. The same item cannot be inserted multiple times:\n`Insert` will return `false` in this case.\n\n## Contributing\n\nFor contributing to Kuku, please see [CONTRIBUTING.md](CONTRIBUTING.md).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2FKuku","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicrosoft%2FKuku","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2FKuku/lists"}