Go Commentary #16: Understand sync.Map

Go sync.Map: The Right Tool for the Right Job

• Context:

  func main() {
      m := make(map[string]int)
  
      go func() {
          for {
              m["blog"] = 1
          }
      }()
  
      go func() {
          for {
              fmt.Println(m["blog"])
          }
      }()
  
      select{} // block-forever trick
  }
  // fatal error: concurrent map read and map write
  
  

• sync.Map:

  • sync.Map takes care of all that locking (or atomic operations) for you - so no manual locking needed, and no worrying about race conditions.

  • reading, writing, and deleting keys faster

    func main() {
      var syncMap sync.Map
  
      // store a key-value pair
      syncMap.Store("blog", "VictoriaMetrics")
  
      // load a value by key "blog"
      value, ok := syncMap.Load("blog")
      fmt.Println(value, ok)
  
      // delete a key-value pair by key "blog"
      syncMap.Delete("blog")
      value, ok = syncMap.Load("blog")
      fmt.Println(value, ok)
    }
  
    // Output:
    // VictoriaMetrics true
    // <nil> false
  

  func (m *Map) Load(key any) (value any, ok bool)
  
  func (m *Map) Store(key, value any)
  func (m *Map) LoadOrStore(key, value any) (actual any, loaded bool)
  
  func (m *Map) Delete(key any)
  func (m *Map) LoadAndDelete(key any) (value any, loaded bool)
  func (m *Map) CompareAndDelete(key, old any) (deleted bool)
  
  func (m *Map) Swap(key, value any) (previous any, loaded bool)
  func (m *Map) CompareAndSwap(key, old, new any) (swapped bool)
  
  func (m *Map) Range(f func(key, value any) bool)
  func (m *Map) Clear()
  

• even when iterate through a map while writing is not safe

    func main() {
      m := make(map[string]int)
  
      go func() {
          for {
              m["blog"] = 1
          }
      }()
  
      go func() {
          for {
              for range m {
                  fmt.Println("iterating")
              }
          }
      }()
  
      select{} // block-forever trick
    }
  
    // fatal error: concurrent map iteration and map write
  

  • With sync.Map.Range, it’s designed to handle concurrent reads and writes during iteration without locking up the entire map. The trade-off, though, is that you might not get a perfectly consistent snapshot of the map while you’re iterating.

• How it works:

  • two separate native maps: the readonly map and the dirty map.

    type Map struct {
      mu Mutex
      read atomic.Pointer[readOnly]
      dirty map[any]*entry
      misses int
    }
  
    type readOnly struct {
      m       map[any]*entry
      amended bool // true if the dirty map contains some key not in m.
    }
  
    type entry struct {
      p atomic.Pointer[any]
    }
  

  • readonly map is where the fast, lock-free lookups happen; built around an atomic.Pointer, which lets multiple goroutines access it without needing to lock anything. (ideal for scenarios where data is mostly being read and not frequently modified) => the readonly map might not always hold the most up-to-date data, therefore dirty map

  • dirty map stores any new entries that get added while the readonly map is still being used for lookups

  

  => dirty map contains all the data from the readonly map, along with any new entries that haven’t yet been promoted to the readonly map

  • when you update a value, all you need to do is update this pointer. Since both the readonly and dirty maps point to the same entry
  

  • The behavior of the pointer in the entry struct defines the state of the entry in the map, and there are 3 possible states:

    • Normal state: This is when the entry is valid. The pointer p is pointing to a real value, and the entry exists in those maps, meaning it’s actively in use and can be read without any issues.

    • Deleted state: When an entry is deleted from a sync.Map, it’s not immediately removed from the readonly maps. Instead, the pointer p is simply set to nil, signaling that the entry has been deleted but still exists in the maps.

    • Expunged state: This is a special state where the key is fully removed. The entry is marked with a special sentinel value that indicates it’s been completely deleted.

  

https://victoriametrics.com/blog/go-sync-map/index.html