gvisor/tools/checklocks

CheckLocks Analyzer

Checklocks is a nogo analyzer that at compile time uses Go's static analysis tools to identify and flag cases where a field that is guarded by a mutex in the same struct is accessed outside of a mutex lock.

The analyzer relies on explicit '// +checklocks:' kind of annotations to identify fields that should be checked for access.

Individual struct members may be protected by annotations that indicate how they must be accessed. These annotations are of the form:

type foo struct {
    mu sync.Mutex
    // +checklocks:mu
    bar int

    foo int  // No annotation on foo means it's not guarded by mu.

    secondMu sync.Mutex

    // Multiple annotations indicate that both must be held but the
    // checker does not assert any lock ordering.
    // +checklocks:secondMu
    // +checklocks:mu
    foobar int
}

The checklocks annotation may also apply to functions. For example:

// +checklocks:f.mu
func (f *foo) doThingLocked() { }

This will check that the "f.mu" is locked for any calls, where possible.

In case of functions which initialize structs that may have annotations one can use the following annotation on the function to disable reporting by the lock checker. The lock checker will still track any mutexes acquired or released but won't report any failures for this function for unguarded field access.

// +checklocks:ignore
func newXXX() *X {
...
}

The checker treats both 'sync.Mutex' and 'sync.RWMutex' identically, i.e, as a sync.Mutex. The checker does not distinguish between read locks vs. exclusive locks and treats all locks as exclusive locks.

For cases the checker is able to correctly handle today please see test/test.go.

The checklocks check also flags any invalid annotations where the mutex annotation refers either to something that is not a 'sync.Mutex' or 'sync.RWMutex' or where the field does not exist at all. This will prevent the annotations from becoming stale over time as fields are renamed, etc.

Currently not supported

1. The analyzer does not correctly handle deferred functions. e.g The following code is not correctly checked by the analyzer. The defer call is never evaluated. As a result if the lock was to be say unlocked twice via deferred functions it would not be caught by the analyzer.

   Similarly deferred anonymous functions are not evaluated either.

type A struct {
  mu sync.Mutex

  // +checklocks:mu
  x int
}

func abc() {
  var a A
  a.mu.Lock()
  defer a.mu.Unlock()
  defer a.mu.Unlock()
  a.x = 1
}

1. Anonymous functions are not correctly evaluated. The analyzer does not currently support specifying annotations on anonymous functions as a result evaluation of a function that accesses protected fields will fail.

type A struct {
  mu sync.Mutex

  // +checklocks:mu
  x int
}

func abc() {
  var a A
  f := func()  { a.x = 1 }  <=== This line will be flagged by analyzer
  a.mu.Lock()
  f()
  a.mu.Unlock()
}

Explicitly Not Supported

1. Checking for embedded mutexes as sync.Locker rather than directly as 'sync.Mutex'. In other words, the checker will not track mutex Lock and Unlock() methods where the mutex is behind an interface dispatch.

An example that we won't handle is shown below (this in fact will fail to build):

type A struct {
  mu sync.Locker

  // +checklocks:mu
  x int
}

func abc() {
   mu sync.Mutex
   a := A{mu: &mu}
   a.x = 1 // This won't be flagged by copylocks checker.
}

1. The checker will not support guards on anything other than the cases described above. For example, global mutexes cannot be referred to by checklocks. Only struct members can be used.

2. The checker will not support checking for lock ordering violations.