From d745e6e41ddf53391b9bb1fc1ee387ead075c10c Mon Sep 17 00:00:00 2001 From: Chris Lu Date: Thu, 30 Oct 2025 23:36:06 -0700 Subject: [PATCH] Fix masterclient vidmap race condition (#7412) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fallback to check master * clean up * parsing * refactor * handle parse error * return error * avoid dup lookup * use batch key * dedup lookup logic * address comments * errors.Join(lookupErrors...) * add a comment * Fix: Critical data race in MasterClient vidMap Fixes a critical data race where resetVidMap() was writing to the vidMap pointer while other methods were reading it concurrently without synchronization. Changes: - Removed embedded *vidMap from MasterClient - Added vidMapLock (sync.RWMutex) to protect vidMap pointer access - Created safe accessor methods (GetLocations, GetDataCenter, etc.) - Updated all direct vidMap accesses to use thread-safe methods - Updated resetVidMap() to acquire write lock during pointer swap The vidMap already has internal locking for its operations, but this fix protects the vidMap pointer itself from concurrent read/write races. Verified with: go test -race ./weed/wdclient/... Impact: - Prevents potential panics from concurrent pointer access - No performance impact - uses RWMutex for read-heavy workloads - Maintains backward compatibility through wrapper methods * fmt * Fix: Critical data race in MasterClient vidMap Fixes a critical data race where resetVidMap() was writing to the vidMap pointer while other methods were reading it concurrently without synchronization. Changes: - Removed embedded *vidMap from MasterClient struct - Added vidMapLock (sync.RWMutex) to protect vidMap pointer access - Created minimal public accessor methods for external packages: * GetLocations, GetLocationsClone, GetVidLocations * LookupFileId, LookupVolumeServerUrl * GetDataCenter - Internal code directly locks and accesses vidMap (no extra indirection) - Updated resetVidMap() to acquire write lock during pointer swap - Updated shell/commands.go to use GetDataCenter() method Design Philosophy: - vidMap already has internal locking for its map operations - This fix specifically protects the vidMap *pointer* from concurrent access - Public methods for external callers, direct locking for internal use - Minimizes wrapper overhead while maintaining thread safety Verified with: go test -race ./weed/wdclient/... (passes) Impact: - Prevents potential panics/crashes from data races - Minimal performance impact (RWMutex for read-heavy workload) - Maintains full backward compatibility * fix more concurrent access * reduce lock scope * Optimize vidMap locking for better concurrency Improved locking strategy based on the understanding that: - vidMapLock protects the vidMap pointer from concurrent swaps - vidMap has internal locks that protect its data structures Changes: 1. Read operations: Grab pointer with RLock, release immediately, then operate - Reduces lock hold time - Allows resetVidMap to proceed sooner - Methods: GetLocations, GetLocationsClone, GetVidLocations, LookupVolumeServerUrl, GetDataCenter 2. Write operations: Changed from Lock() to RLock() - RLock prevents pointer swap during operation - Allows concurrent readers and other writers (serialized by vidMap's lock) - Methods: addLocation, deleteLocation, addEcLocation, deleteEcLocation Benefits: - Significantly reduced lock contention - Better concurrent performance under load - Still prevents all race conditions Verified with: go test -race ./weed/wdclient/... (passes) * Further reduce lock contention in LookupVolumeIdsWithFallback Optimized two loops that were holding RLock for extended periods: Before: - Held RLock during entire loop iteration - Included string parsing and cache lookups - Could block resetVidMap for significant time with large batches After: - Grab vidMap pointer with brief RLock - Release lock immediately - Perform all loop operations on local pointer Impact: - First loop: Cache check on initial volumeIds - Second loop: Double-check after singleflight wait Benefits: - Minimal lock hold time (just pointer copy) - resetVidMap no longer blocked by long loops - Better concurrent performance with large volume ID lists - Still thread-safe (vidMap methods have internal locks) Verified with: go test -race ./weed/wdclient/... (passes) * Add clarifying comments to vidMap helper functions Added inline documentation to each helper function (addLocation, deleteLocation, addEcLocation, deleteEcLocation) explaining the two-level locking strategy: - RLock on vidMapLock prevents resetVidMap from swapping the pointer - vidMap has internal locks that protect the actual map mutations - This design provides optimal concurrency The comments make it clear why RLock (not Lock) is correct and intentional, preventing future confusion about the locking strategy. * Improve encapsulation: Add shallowClone() method to vidMap Added a shallowClone() method to vidMap to improve encapsulation and prevent MasterClient from directly accessing vidMap's internal fields. Changes: 1. Added vidMap.shallowClone() in vid_map.go - Encapsulates the shallow copy logic within vidMap - Makes vidMap responsible for its own state representation - Documented that caller is responsible for thread safety 2. Simplified resetVidMap() in masterclient.go - Uses tail := mc.vidMap.shallowClone() instead of manual field access - Cleaner, more maintainable code - Better adherence to encapsulation principles Benefits: - Improved code organization and maintainability - vidMap internals are now properly encapsulated - Easier to modify vidMap structure in the future - More self-documenting code Verified with: go test -race ./weed/wdclient/... (passes) * Optimize locking: Reduce lock acquisitions and use helper methods Two optimizations to further reduce lock contention and improve code consistency: 1. LookupFileIdWithFallback: Eliminated redundant lock acquisition - Before: Two separate locks to get vidMap and dataCenter - After: Single lock gets both values together - Benefit: 50% reduction in lock/unlock overhead for this hot path 2. KeepConnected: Use GetDataCenter() helper for consistency - Before: Manual lock/unlock to access DataCenter field - After: Use existing GetDataCenter() helper method - Benefit: Better encapsulation and code consistency Impact: - Reduced lock contention in high-traffic lookup path - More consistent use of accessor methods throughout codebase - Cleaner, more maintainable code Verified with: go test -race ./weed/wdclient/... (passes) * Refactor: Extract common locking patterns into helper methods Eliminated code duplication by introducing two helper methods that encapsulate the common locking patterns used throughout MasterClient: 1. getStableVidMap() - For read operations - Acquires lock, gets pointer, releases immediately - Returns stable snapshot for thread-safe reads - Used by: GetLocations, GetLocationsClone, GetVidLocations, LookupFileId, LookupVolumeServerUrl, GetDataCenter 2. withCurrentVidMap(f func(vm *vidMap)) - For write operations - Holds RLock during callback execution - Prevents pointer swap while allowing concurrent operations - Used by: addLocation, deleteLocation, addEcLocation, deleteEcLocation Benefits: - Reduced code duplication (eliminated 48 lines of repetitive locking code) - Centralized locking logic makes it easier to understand and maintain - Self-documenting pattern through named helper methods - Easier to modify locking strategy in the future (single point of change) - Improved readability - accessor methods are now one-liners Code size reduction: ~40% fewer lines for accessor/helper methods Verified with: go test -race ./weed/wdclient/... (passes) * consistent * Fix cache pointer race condition with atomic.Pointer Use atomic.Pointer for vidMap cache field to prevent data races during cache trimming in resetVidMap. This addresses the race condition where concurrent GetLocations calls could read the cache pointer while resetVidMap is modifying it during cache chain trimming. Changes: - Changed cache field from *vidMap to atomic.Pointer[vidMap] - Updated all cache access to use Load() and Store() atomic operations - Updated shallowClone, GetLocations, deleteLocation, deleteEcLocation - Updated resetVidMap to use atomic operations for cache trimming * Merge: Resolve conflict in deleteEcLocation - keep atomic.Pointer and fix bug Resolved merge conflict by combining: 1. Atomic pointer access pattern (from HEAD): cache.Load() 2. Correct method call (from fix): deleteEcLocation (not deleteLocation) Resolution: - Before (HEAD): cachedMap.deleteLocation() - WRONG, reintroduced bug - Before (fix): vc.cache.deleteEcLocation() - RIGHT method, old pattern - After (merged): cachedMap.deleteEcLocation() - RIGHT method, new pattern This preserves both improvements: ✓ Thread-safe atomic.Pointer access pattern ✓ Correct recursive call to deleteEcLocation Verified with: go test -race ./weed/wdclient/... (passes) * Update vid_map.go * remove shallow clone * simplify --- weed/shell/commands.go | 2 +- weed/wdclient/masterclient.go | 148 ++++++++++++++++++++++++++++------ weed/wdclient/vid_map.go | 17 ++-- 3 files changed, 133 insertions(+), 34 deletions(-) diff --git a/weed/shell/commands.go b/weed/shell/commands.go index 62dcfd7f8..55a09e392 100644 --- a/weed/shell/commands.go +++ b/weed/shell/commands.go @@ -116,7 +116,7 @@ func (ce *CommandEnv) AdjustedUrl(location *filer_pb.Location) string { } func (ce *CommandEnv) GetDataCenter() string { - return ce.MasterClient.DataCenter + return ce.MasterClient.GetDataCenter() } func parseFilerUrl(entryPath string) (filerServer string, filerPort int64, path string, err error) { diff --git a/weed/wdclient/masterclient.go b/weed/wdclient/masterclient.go index f3950bc37..320156294 100644 --- a/weed/wdclient/masterclient.go +++ b/weed/wdclient/masterclient.go @@ -35,10 +35,10 @@ type MasterClient struct { masters pb.ServerDiscovery grpcDialOption grpc.DialOption - // TODO: CRITICAL - Data race: resetVidMap() writes to vidMap while other methods read concurrently - // This embedded *vidMap should be changed to a private field protected by sync.RWMutex - // See: https://github.com/seaweedfs/seaweedfs/issues/[ISSUE_NUMBER] - *vidMap + // vidMap stores volume location mappings + // Protected by vidMapLock to prevent race conditions during pointer swaps in resetVidMap + vidMap *vidMap + vidMapLock sync.RWMutex vidMapCacheSize int OnPeerUpdate func(update *master_pb.ClusterNodeUpdate, startFrom time.Time) OnPeerUpdateLock sync.RWMutex @@ -71,8 +71,13 @@ func (mc *MasterClient) GetLookupFileIdFunction() LookupFileIdFunctionType { } func (mc *MasterClient) LookupFileIdWithFallback(ctx context.Context, fileId string) (fullUrls []string, err error) { - // Try cache first using the fast path - fullUrls, err = mc.vidMap.LookupFileId(ctx, fileId) + // Try cache first using the fast path - grab both vidMap and dataCenter in one lock + mc.vidMapLock.RLock() + vm := mc.vidMap + dataCenter := vm.DataCenter + mc.vidMapLock.RUnlock() + + fullUrls, err = vm.LookupFileId(ctx, fileId) if err == nil && len(fullUrls) > 0 { return } @@ -99,7 +104,7 @@ func (mc *MasterClient) LookupFileIdWithFallback(ctx context.Context, fileId str var sameDcUrls, otherDcUrls []string for _, loc := range locations { httpUrl := "http://" + loc.Url + "/" + fileId - if mc.DataCenter != "" && mc.DataCenter == loc.DataCenter { + if dataCenter != "" && dataCenter == loc.DataCenter { sameDcUrls = append(sameDcUrls, httpUrl) } else { otherDcUrls = append(otherDcUrls, httpUrl) @@ -120,6 +125,10 @@ func (mc *MasterClient) LookupVolumeIdsWithFallback(ctx context.Context, volumeI // Check cache first and parse volume IDs once vidStringToUint := make(map[string]uint32, len(volumeIds)) + + // Get stable pointer to vidMap with minimal lock hold time + vm := mc.getStableVidMap() + for _, vidString := range volumeIds { vid, err := strconv.ParseUint(vidString, 10, 32) if err != nil { @@ -127,7 +136,7 @@ func (mc *MasterClient) LookupVolumeIdsWithFallback(ctx context.Context, volumeI } vidStringToUint[vidString] = uint32(vid) - locations, found := mc.GetLocations(uint32(vid)) + locations, found := vm.GetLocations(uint32(vid)) if found && len(locations) > 0 { result[vidString] = locations } else { @@ -149,9 +158,12 @@ func (mc *MasterClient) LookupVolumeIdsWithFallback(ctx context.Context, volumeI stillNeedLookup := make([]string, 0, len(needsLookup)) batchResult := make(map[string][]Location) + // Get stable pointer with minimal lock hold time + vm := mc.getStableVidMap() + for _, vidString := range needsLookup { vid := vidStringToUint[vidString] // Use pre-parsed value - if locations, found := mc.GetLocations(vid); found && len(locations) > 0 { + if locations, found := vm.GetLocations(vid); found && len(locations) > 0 { batchResult[vidString] = locations } else { stillNeedLookup = append(stillNeedLookup, vidString) @@ -196,7 +208,7 @@ func (mc *MasterClient) LookupVolumeIdsWithFallback(ctx context.Context, volumeI GrpcPort: int(masterLoc.GrpcPort), DataCenter: masterLoc.DataCenter, } - mc.vidMap.addLocation(uint32(vid), loc) + mc.addLocation(uint32(vid), loc) locations = append(locations, loc) } @@ -351,7 +363,7 @@ func (mc *MasterClient) tryConnectToMaster(ctx context.Context, master pb.Server if err = stream.Send(&master_pb.KeepConnectedRequest{ FilerGroup: mc.FilerGroup, - DataCenter: mc.DataCenter, + DataCenter: mc.GetDataCenter(), Rack: mc.rack, ClientType: mc.clientType, ClientAddress: string(mc.clientHost), @@ -482,24 +494,110 @@ func (mc *MasterClient) WithClientCustomGetMaster(getMasterF func() pb.ServerAdd }) } +// getStableVidMap gets a stable pointer to the vidMap, releasing the lock immediately. +// This is safe for read operations as the returned pointer is a stable snapshot, +// and the underlying vidMap methods have their own internal locking. +func (mc *MasterClient) getStableVidMap() *vidMap { + mc.vidMapLock.RLock() + vm := mc.vidMap + mc.vidMapLock.RUnlock() + return vm +} + +// withCurrentVidMap executes a function with the current vidMap under a read lock. +// This is for methods that modify vidMap's internal state, ensuring the pointer +// is not swapped by resetVidMap during the operation. The actual map mutations +// are protected by vidMap's internal mutex. +func (mc *MasterClient) withCurrentVidMap(f func(vm *vidMap)) { + mc.vidMapLock.RLock() + defer mc.vidMapLock.RUnlock() + f(mc.vidMap) +} + +// Public methods for external packages to access vidMap safely + +// GetLocations safely retrieves volume locations +func (mc *MasterClient) GetLocations(vid uint32) (locations []Location, found bool) { + return mc.getStableVidMap().GetLocations(vid) +} + +// GetLocationsClone safely retrieves a clone of volume locations +func (mc *MasterClient) GetLocationsClone(vid uint32) (locations []Location, found bool) { + return mc.getStableVidMap().GetLocationsClone(vid) +} + +// GetVidLocations safely retrieves volume locations by string ID +func (mc *MasterClient) GetVidLocations(vid string) (locations []Location, err error) { + return mc.getStableVidMap().GetVidLocations(vid) +} + +// LookupFileId safely looks up URLs for a file ID +func (mc *MasterClient) LookupFileId(ctx context.Context, fileId string) (fullUrls []string, err error) { + return mc.getStableVidMap().LookupFileId(ctx, fileId) +} + +// LookupVolumeServerUrl safely looks up volume server URLs +func (mc *MasterClient) LookupVolumeServerUrl(vid string) (serverUrls []string, err error) { + return mc.getStableVidMap().LookupVolumeServerUrl(vid) +} + +// GetDataCenter safely retrieves the data center +func (mc *MasterClient) GetDataCenter() string { + return mc.getStableVidMap().DataCenter +} + +// Thread-safe helpers for vidMap operations + +// addLocation adds a volume location +func (mc *MasterClient) addLocation(vid uint32, location Location) { + mc.withCurrentVidMap(func(vm *vidMap) { + vm.addLocation(vid, location) + }) +} + +// deleteLocation removes a volume location +func (mc *MasterClient) deleteLocation(vid uint32, location Location) { + mc.withCurrentVidMap(func(vm *vidMap) { + vm.deleteLocation(vid, location) + }) +} + +// addEcLocation adds an EC volume location +func (mc *MasterClient) addEcLocation(vid uint32, location Location) { + mc.withCurrentVidMap(func(vm *vidMap) { + vm.addEcLocation(vid, location) + }) +} + +// deleteEcLocation removes an EC volume location +func (mc *MasterClient) deleteEcLocation(vid uint32, location Location) { + mc.withCurrentVidMap(func(vm *vidMap) { + vm.deleteEcLocation(vid, location) + }) +} + func (mc *MasterClient) resetVidMap() { - tail := &vidMap{ - vid2Locations: mc.vid2Locations, - ecVid2Locations: mc.ecVid2Locations, - DataCenter: mc.DataCenter, - cache: mc.cache, - } + mc.vidMapLock.Lock() + defer mc.vidMapLock.Unlock() - nvm := newVidMap(mc.DataCenter) - nvm.cache = tail + // Preserve the existing vidMap in the cache chain + // No need to clone - the existing vidMap has its own mutex for thread safety + tail := mc.vidMap + + nvm := newVidMap(tail.DataCenter) + nvm.cache.Store(tail) mc.vidMap = nvm - //trim - for i := 0; i < mc.vidMapCacheSize && tail.cache != nil; i++ { - if i == mc.vidMapCacheSize-1 { - tail.cache = nil - } else { - tail = tail.cache + // Trim cache chain to vidMapCacheSize by traversing to the last node + // that should remain and cutting the chain after it + node := tail + for i := 0; i < mc.vidMapCacheSize-1; i++ { + if node.cache.Load() == nil { + return } + node = node.cache.Load() + } + if node != nil { + node.cache.Store(nil) } } diff --git a/weed/wdclient/vid_map.go b/weed/wdclient/vid_map.go index 9d5e5d378..179381b0c 100644 --- a/weed/wdclient/vid_map.go +++ b/weed/wdclient/vid_map.go @@ -4,13 +4,14 @@ import ( "context" "errors" "fmt" - "github.com/seaweedfs/seaweedfs/weed/pb" "math/rand" "strconv" "strings" "sync" "sync/atomic" + "github.com/seaweedfs/seaweedfs/weed/pb" + "github.com/seaweedfs/seaweedfs/weed/glog" ) @@ -41,7 +42,7 @@ type vidMap struct { ecVid2Locations map[uint32][]Location DataCenter string cursor int32 - cache *vidMap + cache atomic.Pointer[vidMap] } func newVidMap(dataCenter string) *vidMap { @@ -135,8 +136,8 @@ func (vc *vidMap) GetLocations(vid uint32) (locations []Location, found bool) { return locations, found } - if vc.cache != nil { - return vc.cache.GetLocations(vid) + if cachedMap := vc.cache.Load(); cachedMap != nil { + return cachedMap.GetLocations(vid) } return nil, false @@ -212,8 +213,8 @@ func (vc *vidMap) addEcLocation(vid uint32, location Location) { } func (vc *vidMap) deleteLocation(vid uint32, location Location) { - if vc.cache != nil { - vc.cache.deleteLocation(vid, location) + if cachedMap := vc.cache.Load(); cachedMap != nil { + cachedMap.deleteLocation(vid, location) } vc.Lock() @@ -235,8 +236,8 @@ func (vc *vidMap) deleteLocation(vid uint32, location Location) { } func (vc *vidMap) deleteEcLocation(vid uint32, location Location) { - if vc.cache != nil { - vc.cache.deleteLocation(vid, location) + if cachedMap := vc.cache.Load(); cachedMap != nil { + cachedMap.deleteEcLocation(vid, location) } vc.Lock()