syncs: add Map.WithLock to allow mutations to the underlying map (#8101)

Some operations cannot be implemented with the prior API:
* Iterating over the map and deleting keys
* Iterating over the map and replacing items
* Calling APIs that expect a native Go map

Add a Map.WithLock method that acquires a write-lock on the map
and then calls a user-provided closure with the underlying Go map.
This allows users to interact with the Map as a regular Go map,
but with the gaurantees that it is concurrent safe.

Updates tailscale/corp#9115

Signed-off-by: Joe Tsai <joetsai@digital-static.net>

syncs/syncs.go

@@ -252,8 +252,10 @@ func (m *Map[K, V]) Delete(key K) {
 	delete(m.m, key)
 }
 
-// Range iterates over the map in undefined order calling f for each entry.
+// Range iterates over the map in an undefined order calling f for each entry.
 // Iteration stops if f returns false. Map changes are blocked during iteration.
+// A read lock is held for the entire duration of the iteration.
+// Use the [WithLock] method instead to mutate the map during iteration.
 func (m *Map[K, V]) Range(f func(key K, value V) bool) {
 	m.mu.RLock()
 	defer m.mu.RUnlock()
@@ -264,6 +266,15 @@ func (m *Map[K, V]) Range(f func(key K, value V) bool) {
 	}
 }
 
+// WithLock calls f with the underlying map.
+// Use of m2 must not escape the duration of this call.
+// The write-lock is held for the entire duration of this call.
+func (m *Map[K, V]) WithLock(f func(m2 map[K]V)) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	f(m.m)
+}
+
 // Len returns the length of the map.
 func (m *Map[K, V]) Len() int {
 	m.mu.RLock()