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