1# xxhash
2
3[](https://pkg.go.dev/github.com/cespare/xxhash/v2)
4[](https://github.com/cespare/xxhash/actions/workflows/test.yml)
5
6xxhash is a Go implementation of the 64-bit [xxHash] algorithm, XXH64. This is a
7high-quality hashing algorithm that is much faster than anything in the Go
8standard library.
9
10This package provides a straightforward API:
11
12```
13func Sum64(b []byte) uint64
14func Sum64String(s string) uint64
15type Digest struct{ ... }
16 func New() *Digest
17```
18
19The `Digest` type implements hash.Hash64. Its key methods are:
20
21```
22func (*Digest) Write([]byte) (int, error)
23func (*Digest) WriteString(string) (int, error)
24func (*Digest) Sum64() uint64
25```
26
27The package is written with optimized pure Go and also contains even faster
28assembly implementations for amd64 and arm64. If desired, the `purego` build tag
29opts into using the Go code even on those architectures.
30
31[xxHash]: http://cyan4973.github.io/xxHash/
32
33## Compatibility
34
35This package is in a module and the latest code is in version 2 of the module.
36You need a version of Go with at least "minimal module compatibility" to use
37github.com/cespare/xxhash/v2:
38
39* 1.9.7+ for Go 1.9
40* 1.10.3+ for Go 1.10
41* Go 1.11 or later
42
43I recommend using the latest release of Go.
44
45## Benchmarks
46
47Here are some quick benchmarks comparing the pure-Go and assembly
48implementations of Sum64.
49
50| input size | purego | asm |
51| ---------- | --------- | --------- |
52| 4 B | 1.3 GB/s | 1.2 GB/s |
53| 16 B | 2.9 GB/s | 3.5 GB/s |
54| 100 B | 6.9 GB/s | 8.1 GB/s |
55| 4 KB | 11.7 GB/s | 16.7 GB/s |
56| 10 MB | 12.0 GB/s | 17.3 GB/s |
57
58These numbers were generated on Ubuntu 20.04 with an Intel Xeon Platinum 8252C
59CPU using the following commands under Go 1.19.2:
60
61```
62benchstat <(go test -tags purego -benchtime 500ms -count 15 -bench 'Sum64$')
63benchstat <(go test -benchtime 500ms -count 15 -bench 'Sum64$')
64```
65
66## Projects using this package
67
68- [InfluxDB](https://github.com/influxdata/influxdb)
69- [Prometheus](https://github.com/prometheus/prometheus)
70- [VictoriaMetrics](https://github.com/VictoriaMetrics/VictoriaMetrics)
71- [FreeCache](https://github.com/coocood/freecache)
72- [FastCache](https://github.com/VictoriaMetrics/fastcache)
73- [Ristretto](https://github.com/dgraph-io/ristretto)
74- [Badger](https://github.com/dgraph-io/badger)
View as plain text