feat: performance optimizations, CI Go 1.21-1.26, CHANGELOG, lint fixes

Performance:
- SearchKNN: sync.Pool for C-type buffers, allocs 4→2, L2 ~12% faster
- SearchBatchKNN: lock-free per-index writes, allocs 412→211
- normalizeVector: in-place modification, no slice return
- Free: remove unnecessary runtime.GC() call

CI:
- Extend Go version matrix to 1.21–1.26

Docs:
- Add CHANGELOG.md (Keep a Changelog format)
- Add benchmark table to README.md
- Link to CHANGELOG.md from README.md

Lint:
- Fix errcheck warnings in test files (os.Remove)

Author: sunhailin-Leo

.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        go: ['1.21', '1.22', '1.23']
+        go: ['1.21', '1.22', '1.23', '1.24', '1.25', '1.26']
 
     steps:
       - name: Checkout code

CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [v1.1.0] - 2026-03-31
+
+### Added
+- Synced hnswlib C++ headers to latest [nmslib/hnswlib master](https://github.com/nmslib/hnswlib/tree/master/hnswlib)
+- New `hnswlib/stop_condition.h` header from upstream
+- `NewWithReplaceDeleted()` — create index with replace-deleted support
+- `AddPointWithReplace()` — add vector reusing deleted slots
+- `Free()` — explicit memory release for HNSW index
+- Nil-safety checks for all public methods (return zero values instead of panicking)
+- Comprehensive unit tests: 19 test functions covering all space types (L2, IP, Cosine)
+- Performance benchmarks: 7 benchmark functions (AddPoint, SearchKNN, BatchOps, SaveLoad)
+- Multi-platform Makefile with `portable`, `opt`, `bench`, `lint` targets
+- Cross-compilation targets: `build-linux-amd64`, `build-linux-arm64`, `build-darwin-amd64`, `build-darwin-arm64`, `build-windows-amd64`
+- Windows support via MinGW-w64 (conditional CGO LDFLAGS, `uint64_t` types)
+- GitHub Actions CI: Linux, macOS, Windows matrix with Go 1.21–1.26
+
+### Changed
+- Upgraded hnswlib from v0.7.0 to latest master
+- All C bridge types changed from `unsigned long int` to `uint64_t` for cross-platform safety (Windows LLP64 compatibility)
+- `SearchKNN` now uses `sync.Pool` to reuse C-type buffers — **allocs reduced 50%** (4 → 2), **L2 search ~12% faster**
+- `SearchBatchKNN` uses lock-free per-index writes instead of mutex — **allocs reduced 49%** (412 → 211)
+- `normalizeVector` optimized to in-place modification (no slice return/copy)
+- Removed unnecessary `runtime.GC()` call from `Free()`
+- `go.mod` bumped to Go 1.21
+
+### Fixed
+- Fixed 3 upstream bugs in `hnswalg.h`: `internal_id` → `internalId` variable name
+- Fixed `UpdateBatchPoints` condition bug (`&&` → `||` for parameter validation)
+
+## [v1.0.4]
+
+### Added
+- `UpdatePoint()` — update vector for existing label
+- `UpdateBatchPoints()` — batch update with concurrent goroutines
+
+## [v1.0.3]
+
+### Added
+- `GetMaxElements()` — query maximum index capacity
+- `GetCurrentElementCount()` — query current element count
+- `GetDeleteCount()` — query soft-deleted element count
+- `GetVectorByLabel()` — retrieve stored vector by label
+
+## [v1.0.2]
+
+### Changed
+- Updated hnswlib to v0.7.0
+
+### Added
+- Batch operations: `AddBatchPoints`, `SearchBatchKNN`
+- Soft delete: `MarkDelete`, `UnmarkDelete`, `GetLabelIsMarkedDeleted`
+- `ResizeIndex()` — dynamically resize index capacity
+
+## [v1.0.1]
+
+### Changed
+- Code formatting improvements
+- Experimental `Unload` API (deprecated in v1.1.0, use `Free`)
+
+## [v1.0.0]
+
+### Added
+- Initial release with hnswlib v0.5.2
+- Core API: `New`, `Load`, `Save`, `AddPoint`, `SearchKNN`, `SetEf`
+- Distance metrics: L2, Inner Product, Cosine

README.md

@@ -174,9 +174,32 @@ pacman -S mingw-w64-x86_64-gcc make
 make build
 ```
 
+## Benchmarks
+
+Measured on Apple M3 Pro, Go 1.23, `-O3 -march=native`, dim=128, 5000 indexed vectors:
+
+| Benchmark | ns/op | B/op | allocs/op |
+|-----------|------:|-----:|----------:|
+| AddPoint (L2) | 1,805,974 | 512 | 1 |
+| AddPoint (Cosine) | 1,476,631 | 512 | 1 |
+| AddBatchPoints (1000×4 goroutines) | 2,949,077,675 | 454 | 9 |
+| SearchKNN (L2, top-10) | 119,831 | 96 | 2 |
+| SearchKNN (Cosine, top-10) | 89,467 | 96 | 2 |
+| SearchBatchKNN (100×4 goroutines) | 4,231,052 | 15,650 | 211 |
+| SaveLoad (5000 vectors) | 16,149,372 | 50 | 1 |
+
+Run benchmarks locally:
+
+```bash
+make opt    # Build with -O3 -march=native
+make bench  # Run all benchmarks
+```
+
 ## Version History
 
-- **v1.1.0** — Synced hnswlib to latest master; added `NewWithReplaceDeleted`, `AddPointWithReplace`, `Free`; nil-safety for all methods; comprehensive tests & benchmarks; multi-platform Makefile; GitHub Actions CI
+See [CHANGELOG.md](CHANGELOG.md) for detailed release notes.
+
+- **v1.1.0** — Synced hnswlib to latest master; performance optimizations; Windows support; comprehensive tests & benchmarks; GitHub Actions CI (Go 1.21–1.26)
 - **v1.0.4** — Added `UpdatePoint`, `UpdateBatchPoints`
 - **v1.0.3** — Added `GetMaxElements`, `GetCurrentElementCount`, `GetDeleteCount`, `GetVectorByLabel`
 - **v1.0.2** — Updated hnswlib to 0.7.0; added batch operations, delete/unmark, resize
@@ -186,5 +209,3 @@ make build
 ## License
 
 MIT — see [LICENSE](LICENSE) for details.
-| cosine    | cosine similarity |
-| l2        | l2                |

hnsw.go

@@ -12,7 +12,6 @@ package hnswgo
 import "C"
 import (
 	"math"
-	"runtime"
 	"sync"
 	"unsafe"
 )
@@ -86,7 +85,6 @@ func (h *HNSW) Free() bool {
 	}
 	C.freeHNSW(h.index, spaceChar(h.spaceType))
 	h.index = nil
-	runtime.GC()
 	return true
 }
 
@@ -107,17 +105,16 @@ func (h *HNSW) Save(location string) bool {
 	return true
 }
 
-// normalizeVector normalize vector
-func normalizeVector(vector []float32) []float32 {
-	var norm float32
-	for i := 0; i < len(vector); i++ {
-		norm += vector[i] * vector[i]
+// normalizeVector normalizes a vector in-place to unit length.
+func normalizeVector(vector []float32) {
+	var squaredSum float32
+	for _, v := range vector {
+		squaredSum += v * v
 	}
-	norm = 1.0 / (float32(math.Sqrt(float64(norm))) + 1e-15)
-	for i := 0; i < len(vector); i++ {
-		vector[i] = vector[i] * norm
+	invNorm := float32(1.0 / (math.Sqrt(float64(squaredSum)) + 1e-15))
+	for i := range vector {
+		vector[i] *= invNorm
 	}
-	return vector
 }
 
 // AddPoint adds a point to the index.
@@ -126,7 +123,7 @@ func (h *HNSW) AddPoint(vector []float32, label uint32) bool {
 		return false
 	}
 	if h.normalize {
-		vector = normalizeVector(vector)
+		normalizeVector(vector)
 	}
 	C.addPoint(h.index, (*C.float)(unsafe.Pointer(&vector[0])), C.uint64_t(label), C.bool(false))
 	return true
@@ -139,7 +136,7 @@ func (h *HNSW) AddPointWithReplace(vector []float32, label uint32) bool {
 		return false
 	}
 	if h.normalize {
-		vector = normalizeVector(vector)
+		normalizeVector(vector)
 	}
 	C.addPoint(h.index, (*C.float)(unsafe.Pointer(&vector[0])), C.uint64_t(label), C.bool(true))
 	return true
@@ -172,55 +169,77 @@ func (h *HNSW) AddBatchPoints(vectors [][]float32, labels []uint32, coroutines i
 	return true
 }
 
-// SearchKNN search points on graph with knn-algorithm
+// searchBufferPool reuses C-type slices to reduce allocations in SearchKNN.
+var searchBufferPool = sync.Pool{
+	New: func() any {
+		return &searchBuffer{}
+	},
+}
+
+type searchBuffer struct {
+	labels []C.uint64_t
+	dists  []C.float
+}
+
+// SearchKNN searches for the N nearest neighbors of the given vector.
 func (h *HNSW) SearchKNN(vector []float32, N int) ([]uint32, []float32) {
 	if h.index == nil {
 		return nil, nil
 	}
-	Clabel := make([]C.uint64_t, N, N)
-	Cdist := make([]C.float, N, N)
 	if h.normalize {
-		vector = normalizeVector(vector)
+		normalizeVector(vector)
 	}
-	numResult := int(C.searchKnn(h.index, (*C.float)(unsafe.Pointer(&vector[0])), C.int(N), &Clabel[0], &Cdist[0]))
-	labels := make([]uint32, N)
-	dists := make([]float32, N)
+
+	buf := searchBufferPool.Get().(*searchBuffer)
+	if cap(buf.labels) < N {
+		buf.labels = make([]C.uint64_t, N)
+		buf.dists = make([]C.float, N)
+	} else {
+		buf.labels = buf.labels[:N]
+		buf.dists = buf.dists[:N]
+	}
+
+	numResult := int(C.searchKnn(h.index, (*C.float)(unsafe.Pointer(&vector[0])), C.int(N), &buf.labels[0], &buf.dists[0]))
+
+	labels := make([]uint32, numResult)
+	dists := make([]float32, numResult)
 	for i := 0; i < numResult; i++ {
-		labels[i] = uint32(Clabel[i])
-		dists[i] = float32(Cdist[i])
+		labels[i] = uint32(buf.labels[i])
+		dists[i] = float32(buf.dists[i])
 	}
-	return labels[:numResult], dists[:numResult]
+
+	searchBufferPool.Put(buf)
+	return labels, dists
 }
 
-// SearchBatchKNN search multiple points on graph with knn-algorithm
+// SearchBatchKNN searches for the N nearest neighbors of multiple vectors concurrently.
 func (h *HNSW) SearchBatchKNN(vectors [][]float32, N, coroutines int) ([][]uint32, [][]float32) {
+	totalVectors := len(vectors)
 	if coroutines < 1 {
 		coroutines = 1
 	}
+	if coroutines > totalVectors {
+		coroutines = totalVectors
+	}
 
-	var lock sync.Mutex
-	labelList := make([][]uint32, len(vectors))
-	distList := make([][]float32, len(vectors))
+	labelList := make([][]uint32, totalVectors)
+	distList := make([][]float32, totalVectors)
 
-	b := len(vectors) / coroutines
+	batchSize := totalVectors / coroutines
 	var wg sync.WaitGroup
 	for i := 0; i < coroutines; i++ {
-		wg.Add(1)
-
-		end := (i + 1) * b
-		if i == coroutines-1 && len(vectors) > end {
-			end = len(vectors)
+		start := i * batchSize
+		end := start + batchSize
+		if i == coroutines-1 {
+			end = totalVectors
 		}
-		go func(i int) {
+		wg.Add(1)
+		go func(start, end int) {
 			defer wg.Done()
-			for j := i * b; j < end; j++ {
-				labels, dist := h.SearchKNN(vectors[j], N)
-				lock.Lock()
-				labelList[j] = labels
-				distList[j] = dist
-				lock.Unlock()
+			for j := start; j < end; j++ {
+				labelList[j], distList[j] = h.SearchKNN(vectors[j], N)
 			}
-		}(i)
+		}(start, end)
 	}
 	wg.Wait()
 	return labelList, distList

hnsw_benchmark_test.go

@@ -195,6 +195,6 @@ func BenchmarkSaveLoad(b *testing.B) {
 		if hnsw != nil {
 			hnsw.Free()
 		}
-		os.Remove(tmpFile)
+		_ = os.Remove(tmpFile)
 	})
 }

hnsw_test.go

@@ -187,7 +187,7 @@ func TestHNSW_SaveLoad(t *testing.T) {
 		t.Run(spaceType, func(t *testing.T) {
 			tempDir := os.TempDir()
 			tempFile := filepath.Join(tempDir, "hnsw_test_"+spaceType+".bin")
-			t.Cleanup(func() { os.Remove(tempFile) })
+			t.Cleanup(func() { _ = os.Remove(tempFile) })
 
 			// Create and populate index
 			hnsw := New(10, 16, 200, 42, 1000, spaceType)