| 1 | # xxhash
|
|---|
| 2 |
|
|---|
| 3 | [](https://pkg.go.dev/github.com/cespare/xxhash/v2)
|
|---|
| 4 | [](https://github.com/cespare/xxhash/actions/workflows/test.yml)
|
|---|
| 5 |
|
|---|
| 6 | xxhash is a Go implementation of the 64-bit
|
|---|
| 7 | [xxHash](http://cyan4973.github.io/xxHash/) algorithm, XXH64. This is a
|
|---|
| 8 | high-quality hashing algorithm that is much faster than anything in the Go
|
|---|
| 9 | standard library.
|
|---|
| 10 |
|
|---|
| 11 | This package provides a straightforward API:
|
|---|
| 12 |
|
|---|
| 13 | ```
|
|---|
| 14 | func Sum64(b []byte) uint64
|
|---|
| 15 | func Sum64String(s string) uint64
|
|---|
| 16 | type Digest struct{ ... }
|
|---|
| 17 | func New() *Digest
|
|---|
| 18 | ```
|
|---|
| 19 |
|
|---|
| 20 | The `Digest` type implements hash.Hash64. Its key methods are:
|
|---|
| 21 |
|
|---|
| 22 | ```
|
|---|
| 23 | func (*Digest) Write([]byte) (int, error)
|
|---|
| 24 | func (*Digest) WriteString(string) (int, error)
|
|---|
| 25 | func (*Digest) Sum64() uint64
|
|---|
| 26 | ```
|
|---|
| 27 |
|
|---|
| 28 | This implementation provides a fast pure-Go implementation and an even faster
|
|---|
| 29 | assembly implementation for amd64.
|
|---|
| 30 |
|
|---|
| 31 | ## Compatibility
|
|---|
| 32 |
|
|---|
| 33 | This package is in a module and the latest code is in version 2 of the module.
|
|---|
| 34 | You need a version of Go with at least "minimal module compatibility" to use
|
|---|
| 35 | github.com/cespare/xxhash/v2:
|
|---|
| 36 |
|
|---|
| 37 | * 1.9.7+ for Go 1.9
|
|---|
| 38 | * 1.10.3+ for Go 1.10
|
|---|
| 39 | * Go 1.11 or later
|
|---|
| 40 |
|
|---|
| 41 | I recommend using the latest release of Go.
|
|---|
| 42 |
|
|---|
| 43 | ## Benchmarks
|
|---|
| 44 |
|
|---|
| 45 | Here are some quick benchmarks comparing the pure-Go and assembly
|
|---|
| 46 | implementations of Sum64.
|
|---|
| 47 |
|
|---|
| 48 | | input size | purego | asm |
|
|---|
| 49 | | --- | --- | --- |
|
|---|
| 50 | | 5 B | 979.66 MB/s | 1291.17 MB/s |
|
|---|
| 51 | | 100 B | 7475.26 MB/s | 7973.40 MB/s |
|
|---|
| 52 | | 4 KB | 17573.46 MB/s | 17602.65 MB/s |
|
|---|
| 53 | | 10 MB | 17131.46 MB/s | 17142.16 MB/s |
|
|---|
| 54 |
|
|---|
| 55 | These numbers were generated on Ubuntu 18.04 with an Intel i7-8700K CPU using
|
|---|
| 56 | the following commands under Go 1.11.2:
|
|---|
| 57 |
|
|---|
| 58 | ```
|
|---|
| 59 | $ go test -tags purego -benchtime 10s -bench '/xxhash,direct,bytes'
|
|---|
| 60 | $ go test -benchtime 10s -bench '/xxhash,direct,bytes'
|
|---|
| 61 | ```
|
|---|
| 62 |
|
|---|
| 63 | ## Projects using this package
|
|---|
| 64 |
|
|---|
| 65 | - [InfluxDB](https://github.com/influxdata/influxdb)
|
|---|
| 66 | - [Prometheus](https://github.com/prometheus/prometheus)
|
|---|
| 67 | - [VictoriaMetrics](https://github.com/VictoriaMetrics/VictoriaMetrics)
|
|---|
| 68 | - [FreeCache](https://github.com/coocood/freecache)
|
|---|
| 69 | - [FastCache](https://github.com/VictoriaMetrics/fastcache)
|
|---|
