Replace SetFinalizer with AddCleanup for Go 1.24+

Switch to runtime.AddCleanup for more reliable resource cleanup.
This provides better finalization behavior compared to SetFinalizer.
Uses atomic operations to prevent race conditions during cleanup.

Author: oschwald

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changes
 
+## 2.0.0-beta.10
+
+- Replaced `runtime.SetFinalizer` with `runtime.AddCleanup` for resource
+  cleanup in Go 1.24+. This provides more reliable finalization behavior and
+  better garbage collection performance.
+
 ## 2.0.0-beta.9 - 2025-08-23
 
 - **SECURITY**: Fixed integer overflow vulnerability in search tree size

reader.go

@@ -112,6 +112,7 @@ import (
 	"net/netip"
 	"os"
 	"runtime"
+	"sync/atomic"
 	"time"
 
 	"github.com/oschwald/maxminddb-golang/v2/internal/decoder"
@@ -122,6 +123,12 @@ const dataSectionSeparatorSize = 16
 
 var metadataStartMarker = []byte("\xAB\xCD\xEFMaxMind.com")
 
+// mmapCleanup holds the data needed to safely cleanup memory-mapped files
+type mmapCleanup struct {
+	data      []byte
+	hasMapped *atomic.Bool
+}
+
 // Reader holds the data corresponding to the MaxMind DB file. Its only public
 // field is Metadata, which contains the metadata from the MaxMind DB file.
 //
@@ -134,7 +141,7 @@ type Reader struct {
 	ipv4Start         uint
 	ipv4StartBitDepth int
 	nodeOffsetMult    uint
-	hasMappedFile     bool
+	hasMappedFile     atomic.Bool
 }
 
 // Metadata holds the metadata decoded from the MaxMind DB file.
@@ -252,8 +259,16 @@ func Open(file string, options ...ReaderOption) (*Reader, error) {
 		return nil, err
 	}
 
-	reader.hasMappedFile = true
-	runtime.SetFinalizer(reader, (*Reader).Close)
+	reader.hasMappedFile.Store(true)
+	cleanup := &mmapCleanup{
+		data:      data,
+		hasMapped: &reader.hasMappedFile,
+	}
+	runtime.AddCleanup(reader, func(mc *mmapCleanup) {
+		if mc.hasMapped.CompareAndSwap(true, false) {
+			_ = munmap(mc.data)
+		}
+	}, cleanup)
 	return reader, nil
 }
 
@@ -281,9 +296,7 @@ func openFallback(f *os.File, size int) (data []byte, err error) {
 // Close returns the resources used by the database to the system.
 func (r *Reader) Close() error {
 	var err error
-	if r.hasMappedFile {
-		runtime.SetFinalizer(r, nil)
-		r.hasMappedFile = false
+	if r.hasMappedFile.CompareAndSwap(true, false) {
 		err = munmap(r.buffer)
 	}
 	r.buffer = nil
@@ -384,7 +397,7 @@ func (r *Reader) Lookup(ip netip.Addr) Result {
 	}
 	offset, err := r.resolveDataPointer(pointer)
 	return Result{
-		decoder:   r.decoder,
+		reader:    r,
 		ip:        ip,
 		offset:    uint(offset),
 		prefixLen: uint8(prefixLen),
@@ -399,7 +412,7 @@ func (r *Reader) LookupOffset(offset uintptr) Result {
 		return Result{err: errors.New("cannot call LookupOffset on a closed database")}
 	}
 
-	return Result{decoder: r.decoder, offset: uint(offset)}
+	return Result{reader: r, offset: uint(offset)}
 }
 
 func (r *Reader) setIPv4Start() error {

result.go

@@ -3,8 +3,6 @@ package maxminddb
 import (
 	"math"
 	"net/netip"
-
-	"github.com/oschwald/maxminddb-golang/v2/internal/decoder"
 )
 
 const notFound uint = math.MaxUint
@@ -13,7 +11,7 @@ const notFound uint = math.MaxUint
 type Result struct {
 	ip        netip.Addr
 	err       error
-	decoder   decoder.ReflectionDecoder
+	reader    *Reader
 	offset    uint
 	prefixLen uint8
 }
@@ -37,7 +35,7 @@ func (r Result) Decode(v any) error {
 		return nil
 	}
 
-	return r.decoder.Decode(r.offset, v)
+	return r.reader.decoder.Decode(r.offset, v)
 }
 
 // DecodePath unmarshals a value from data section into v, following the
@@ -94,7 +92,7 @@ func (r Result) DecodePath(v any, path ...any) error {
 	if r.offset == notFound {
 		return nil
 	}
-	return r.decoder.DecodePath(r.offset, path, v)
+	return r.reader.decoder.DecodePath(r.offset, path, v)
 }
 
 // Err provides a way to check whether there was an error during the lookup

traverse.go

@@ -192,7 +192,7 @@ func (r *Reader) NetworksWithin(prefix netip.Prefix, options ...NetworksOption)
 					}
 
 					ok := yield(Result{
-						decoder:   r.decoder,
+						reader:    r,
 						ip:        mappedIP(node.ip),
 						offset:    uint(offset),
 						prefixLen: uint8(node.bit),