{"id":24800090,"url":"https://github.com/simdhash/clhash","last_synced_at":"2026-05-22T02:05:29.842Z","repository":{"id":66054821,"uuid":"57042471","full_name":"simdhash/clhash","owner":"simdhash","description":"C library implementing the ridiculously fast CLHash  hashing function","archived":false,"fork":false,"pushed_at":"2024-04-04T02:34:39.000Z","size":29,"stargazers_count":274,"open_issues_count":3,"forks_count":29,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-03-31T05:03:46.406Z","etag":null,"topics":["hash","hashing"],"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/simdhash.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":"2016-04-25T13:08:28.000Z","updated_at":"2025-03-28T04:56:25.000Z","dependencies_parsed_at":"2024-10-26T20:28:58.188Z","dependency_job_id":"829e499d-8abf-4c2e-8ffa-ac281b589398","html_url":"https://github.com/simdhash/clhash","commit_stats":null,"previous_names":["simdhash/clhash"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simdhash%2Fclhash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simdhash%2Fclhash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simdhash%2Fclhash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simdhash%2Fclhash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simdhash","download_url":"https://codeload.github.com/simdhash/clhash/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247601449,"owners_count":20964864,"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":["hash","hashing"],"created_at":"2025-01-30T03:09:13.831Z","updated_at":"2026-05-22T02:05:29.822Z","avatar_url":"https://github.com/simdhash.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# clhash\n[![CI](https://github.com/simdhash/clhash/actions/workflows/ci.yml/badge.svg)](https://github.com/simdhash/clhash/actions/workflows/ci.yml)\n\nC library implementing the ridiculously fast CLHash hashing function (with C++ wrappers)\n\n\n CLHash is a very fast hashing function that uses\n carry-less multiplication. It runs on recent x64 processors\n (Haswell or better, via PCLMULQDQ + SSE4.2) and on 64-bit ARM\n processors with the crypto extension that provides PMULL\n (e.g., Apple Silicon, modern Cortex-A cores, AWS Graviton).\n\nCLHash has the following characteristics :\n\n* On a recent Intel processor (e.g., Skylake), it can hash input strings at a speed of 0.1 cycles per byte for sufficiently long strings. You read this right: it is simply ridiculously fast.\n* On 64-bit ARM with PMULL (e.g., Apple Silicon), it is similarly fast.\n* It has strong theoretical guarantees: XOR universality of short strings and excellent almost universality for longer strings.\n* The x86 and ARM implementations are bit-for-bit compatible: identical (seed, input) pairs produce the same 64-bit hash on either platform. This is verified by a known-answer test in `tests/unit.c`.\n\nFor details, please see the research article:\n\n- Daniel Lemire, Owen Kaser, Faster 64-bit universal hashing using carry-less multiplications, Journal of Cryptographic Engineering 6 (3), 2016. http://arxiv.org/abs/1503.03465\n\n\n## How fast is it?\n\nA standard fast but non-random hash function is a simple recursive function like so:\n\n```c\nuint64_t javalikehash(char *input, size_t length) {\n  uint64_t sum = 0;\n  for(size_t i = 0; i \u003c length; ++i) sum = 31 * sum + (uint64_t) input[i];\n  return sum;\n}\n```\n\nYou should expect clhash to be between **20 to 40 times** faster than this reference\nhash function for input spanning hundreds of bytes or more.\n\n\n## Requirements\n\n\n* On x64, you need PCLMULQDQ + SSE4.2 (Haswell from 2013 or later in practice). On older\n  x64 chips it will either fail to build or be slow. The Makefile and\n  CMake build pass `-msse4.2 -mpclmul -march=native` on x86. Virtually all x64 processors \n  today fit this requirement.\n* On 64-bit ARM (AArch64), you need the crypto extension that provides the\n  PMULL/PMULL2 instructions (advertised via `HWCAP_PMULL` on Linux, and\n  always present on Apple Silicon). The build passes `-march=armv8-a+crypto`\n  on ARM. Virtually all 64-bit ARM processors support this feature today.\n\nPOWER and other architectures are not currently supported; the build will\nfail at preprocessing with a clear `#error`.\n\nIf your compiler is not C99 compliant... please get better one.\n\n\n## Usage\n\n ```bash\n make\n ./unit\n ```\nCompile option: if you define CLHASH_BITMIX during compilation, extra work is done to\npass smhasher's avalanche test succesfully. Disabled by default.\n\n## Code sample\n\n```C\n#include \u003cassert.h\u003e\n\n#include \"clhash.h\"\n\nint main() {\n    void * random =  get_random_key_for_clhash(UINT64_C(0x23a23cf5033c3c81),UINT64_C(0xb3816f6a2c68e530));\n    uint64_t hashvalue1 = clhash(random,\"my dog\",6);\n    uint64_t hashvalue2 = clhash(random,\"my cat\",6);\n    uint64_t hashvalue3 = clhash(random,\"my dog\",6);\n    assert(hashvalue1 == hashvalue3);\n    assert(hashvalue1 != hashvalue2);// very likely to be true\n    free(random);\n    return 0;\n}\n```\n\n## Simple benchmark\n\n ```bash\n make\n ./benchmark\n ```\n\n ## C++\n\nIf you prefer the convenience of a C++ interface with support for stl::vector and std::string,\nyou can create a clhasher object instead.\n\n```C\n#include \u003cassert.h\u003e\n#include \u003ccstdio\u003e\n#include \u003cvector\u003e\n\n#include \"clhash.h\"\n\n\nint main(void) {\n    clhasher h(UINT64_C(0x23a23cf5033c3c81),UINT64_C(0xb3816f6a2c68e530));\n    std::vector\u003cint\u003e vec{1,3,4,5,2,24343};\n    uint64_t vechash = h(vec);\n\n    uint64_t arrayhash = h(vec.data(), vec.size());\n\n    assert(vechash == arrayhash);\n\n    uint64_t cstringhash = h(\"o hai wurld\");\n    uint64_t stringhash = h(std::string(\"o hai wurld\"));\n    assert(cstringhash == stringhash);\n}\n```\n\n ```bash\n make\n ./cppunit\n ```\n\n\n\n## CMake\n\nYou can also build with CMake:\n\n```bash\ncmake -S . -B build\ncmake --build build -j\n```\n\nRun tests with CTest:\n\n```bash\nctest --test-dir build --output-on-failure\n```\n\nEnable `CLHASH_BITMIX` at configure time:\n\n```bash\ncmake -S . -B build -DCLHASH_ENABLE_BITMIX=ON\ncmake --build build -j\n```\n\n### Install\n\nThe CMake build provides install rules. Pick a prefix and run:\n\n```bash\ncmake -S . -B build -DCMAKE_INSTALL_PREFIX=/usr/local\ncmake --build build -j\ncmake --install build       # may need sudo depending on the prefix\n```\n\nThis installs:\n\n* `lib/libclhash.a` — the static library\n* `include/clhash.h` — the public header (also provides the C++ `clhasher` wrapper)\n* `lib/cmake/clhash/clhash{Config,ConfigVersion,Targets}.cmake` — a CMake\n  package config so downstream projects can `find_package(clhash)`\n\nDownstream CMake usage looks like:\n\n```cmake\nfind_package(clhash 1.0 REQUIRED)\nadd_executable(myapp main.c)\ntarget_link_libraries(myapp PRIVATE clhash::clhash)\n```\n\nIf you are vendoring clhash via `add_subdirectory()` and do not want the\ninstall rules to be inherited, pass `-DCLHASH_INSTALL=OFF`.\n\n## Drop-in usage (no build system required)\n\nclhash is deliberately tiny: it is a **single C source file** plus a **single\npublic header**. If you do not want to deal with a build system, just copy\n\n* `src/clhash.c`\n* `include/clhash.h`\n\ninto your project and compile `clhash.c` with your other sources. The only\nrequirements are a C99 (or newer) compiler and the right architecture flag:\n\n* `-msse4.2 -mpclmul` (or `-march=native`) on x86-64\n* `-march=armv8-a+crypto` on 64-bit ARM\n\nFor example, on Apple Silicon:\n\n```bash\ncc -O3 -march=armv8-a+crypto -std=c99 -Iinclude -c src/clhash.c\ncc -O3 -march=armv8-a+crypto -std=c99 -Iinclude my_program.c clhash.o -o my_program\n```\n\nThe library has no external dependencies beyond the C standard library.\n\n\n\n## Citation\n\nIf you use this library in your work, please cite:\n\n```bibtex\n@article{lemire2016faster,\n    title={Faster 64-bit universal hashing using carry-less multiplications},\n    author={Lemire, Daniel and Kaser, Owen},\n    journal={Journal of Cryptographic Engineering},\n    volume={6},\n    number={3},\n    pages={171--185},\n    year={2016}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimdhash%2Fclhash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimdhash%2Fclhash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimdhash%2Fclhash/lists"}