README
¶
xorsimd
xorsimd provides high-throughput XOR operations for byte slices.
On amd64 it selects AVX-512/AVX2/SSE2 implementations, and falls back to
portable Go code on other architectures.
Install
go get github.com/templexxx/xorsimd
Quick Start
package main
import "github.com/templexxx/xorsimd"
func main() {
a := []byte{1, 2, 3, 4}
b := []byte{9, 8, 7, 6}
dst := make([]byte, 4)
// dst = a ^ b
n := xorsimd.Bytes(dst, a, b)
_ = n
// dst = src[0] ^ src[1] ^ src[2] ...
src := [][]byte{a, b, []byte{1, 1, 1, 1}}
n = xorsimd.Encode(dst, src)
_ = n
}
API Notes
Encode(dst, src)XORs all rows insrcintodstand returns the number of bytes processed.Encoderequireslen(src) >= 1.Bytes(dst, a, b)is a convenience wrapper aroundEncode.Bytes8,Bytes16,Bytes8Align, andBytes16Alignare fixed-size helpers.BytesAprocesseslen(a)bytes;BytesBprocesseslen(b)bytes.
All APIs may reuse overlapping slices. For correctness, callers must ensure the input slices are long enough for the selected function variant.
Performance
Performance mainly depends on:
- CPU SIMD instruction support.
- Number of input source rows.
- Slice size.
Benchmark formula:
I/O = (src_num + 1) * vector_size / cost
Test environment:
- AWS c5d.xlarge
- Intel Xeon Platinum 8124M @ 3.00GHz
- Single physical core
| Src Num | Vector Size | AVX512 I/O (MB/s) | AVX2 I/O (MB/s) | SSE2 I/O (MB/s) |
|---|---|---|---|---|
| 5 | 4KB | 270403.73 | 142825.25 | 74443.91 |
| 5 | 1MB | 26948.34 | 26887.37 | 26950.65 |
| 5 | 8MB | 17881.32 | 17212.56 | 16402.97 |
| 10 | 4KB | 190445.30 | 102953.59 | 53244.04 |
| 10 | 1MB | 26424.44 | 26618.65 | 26094.39 |
| 10 | 8MB | 15471.31 | 14866.72 | 13565.80 |
Run Tests and Benchmarks
go test ./...
go test -bench=. -benchmem
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var EnableAVX512 = true
EnableAVX512 controls whether AVX-512 is considered during feature detection. Note: instruction-path selection is decided at package initialization, so changing this value afterwards does not refresh the selected backend.
Functions ¶
func Bytes ¶ added in v0.2.1
Bytes XORs a and b into dst. The source and destination may overlap.
Bytes returns the number of bytes processed, which is the minimum of len(dst), len(a), and len(b).
func Bytes8 ¶ added in v0.2.1
func Bytes8(dst, a, b []byte)
Bytes8 XORs exactly 8 bytes from a and b into dst. Each slice must have length >= 8, otherwise it panics.
func Bytes8Align ¶ added in v0.4.1
func Bytes8Align(dst, a, b []byte)
Bytes8Align XORs exactly 8 bytes from a and b into dst. Each slice must have length >= 8, otherwise it panics. On amd64, explicit alignment is not required; this function exists for API compatibility with non-amd64 implementations.
func Bytes16 ¶ added in v0.2.1
func Bytes16(dst, a, b []byte)
Bytes16 XORs exactly 16 bytes from a and b into dst. Each slice must have length >= 16, otherwise it panics.
func Bytes16Align ¶ added in v0.4.1
func Bytes16Align(dst, a, b []byte)
Bytes16Align XORs exactly 16 bytes from a and b into dst. Each slice must have length >= 16, otherwise it panics. On amd64, explicit alignment is not required; this function exists for API compatibility with non-amd64 implementations.
func BytesA ¶ added in v0.3.1
func BytesA(dst, a, b []byte)
BytesA XORs len(a) bytes from a and b into dst. Callers must ensure len(dst) >= len(a) and len(b) >= len(a).
This helper is intended for small slices where setup overhead dominates. For larger slices, Bytes is usually faster.
func BytesB ¶ added in v0.3.1
func BytesB(dst, a, b []byte)
BytesB XORs len(b) bytes from a and b into dst. Callers must ensure len(dst) >= len(b) and len(a) >= len(b).
This helper is intended for small slices where setup overhead dominates. For larger slices, Bytes is usually faster.
Types ¶
This section is empty.
Source Files