Mix checklocks and atomic analyzers.

This change makes the checklocks analyzer considerable more powerful, adding:
* The ability to traverse complex structures, e.g. to have multiple nested
  fields as part of the annotation.
* The ability to resolve simple anonymous functions and closures, and perform
  lock analysis across these invocations. This does not apply to closures that
  are passed elsewhere, since it is not possible to know the context in which
  they might be invoked.
* The ability to annotate return values in addition to receivers and other
  parameters, with the same complex structures noted above.
* Ignoring locking semantics for "fresh" objects, i.e. objects that are
  allocated in the local frame (typically a new-style function).
* Sanity checking of locking state across block transitions and returns, to
  ensure that no unexpected locks are held.

Note that initially, most of these findings are excluded by a comprehensive
nogo.yaml. The findings that are included are fundamental lock violations.
The changes here should be relatively low risk, minor refactorings to either
include necessary annotations to simplify the code structure (in general
removing closures in favor of methods) so that the analyzer can be easily
track the lock state.

This change additional includes two changes to nogo itself:
* Sanity checking of all types to ensure that the binary and ast-derived
  types have a consistent objectpath, to prevent the bug above from occurring
  silently (and causing much confusion). This also requires a trick in
  order to ensure that serialized facts are consumable downstream. This can
  be removed with https://go-review.googlesource.com/c/tools/+/331789 merged.
* A minor refactoring to isolation the objdump settings in its own package.
  This was originally used to implement the sanity check above, but this
  information is now being passed another way. The minor refactor is preserved
  however, since it cleans up the code slightly and is minimal risk.

PiperOrigin-RevId: 382613300

1 files changed, 77 insertions, 681 deletions

diff --git a/tools/checklocks/checklocks.go b/tools/checklocks/checklocks.go
index 1e877d394..180f8873f 100644
--- a/tools/checklocks/checklocks.go
+++ b/tools/checklocks/checklocks.go
@@ -13,32 +13,19 @@
 // limitations under the License.
 
 // Package checklocks performs lock analysis to identify and flag unprotected
-// access to field annotated with a '// +checklocks:<mutex-name>' annotation.
+// access to annotated fields.
 //
-// For detailed ussage refer to README.md in the same directory.
+// For detailed usage refer to README.md in the same directory.
 package checklocks
 
 import (
-	"bytes"
-	"fmt"
 	"go/ast"
 	"go/token"
 	"go/types"
-	"reflect"
-	"regexp"
-	"strconv"
-	"strings"
 
 	"golang.org/x/tools/go/analysis"
 	"golang.org/x/tools/go/analysis/passes/buildssa"
 	"golang.org/x/tools/go/ssa"
-	"gvisor.dev/gvisor/pkg/log"
-)
-
-const (
-	checkLocksAnnotation = "// +checklocks:"
-	checkLocksIgnore     = "// +checklocksignore"
-	checkLocksFail       = "// +checklocksfail"
 )
 
 // Analyzer is the main entrypoint.
@@ -47,712 +34,121 @@ var Analyzer = &analysis.Analyzer{
 	Doc:       "checks lock preconditions on functions and fields",
 	Run:       run,
 	Requires:  []*analysis.Analyzer{buildssa.Analyzer},
-	FactTypes: []analysis.Fact{(*lockFieldFacts)(nil), (*lockFunctionFacts)(nil)},
-}
-
-// lockFieldFacts apply on every struct field protected by a lock or that is a
-// lock.
-type lockFieldFacts struct {
-	// GuardedBy tracks the names and field numbers that guard this field.
-	GuardedBy map[string]int
-
-	// IsMutex is true if the field is of type sync.Mutex.
-	IsMutex bool
-
-	// IsRWMutex is true if the field is of type sync.RWMutex.
-	IsRWMutex bool
-
-	// FieldNumber is the number of this field in the struct.
-	FieldNumber int
-}
-
-// AFact implements analysis.Fact.AFact.
-func (*lockFieldFacts) AFact() {}
-
-type functionGuard struct {
-	// ParameterNumber is the index of the object that contains the guarding mutex.
-	// This is required during SSA analysis as field names and parameters names are
-	// not available in SSA. For example, from the example below ParameterNumber would
-	// be 1 and FieldNumber would correspond to the field number of 'mu' within b's type.
-	//
-	// //+checklocks:b.mu
-	// func (a *A) method(b *B, c *C) {
-	//   ...
-	// }
-	ParameterNumber int
-
-	// FieldNumber is the field index of the mutex in the parameter's struct
-	// type. Refer to example above for more details.
-	FieldNumber int
-}
-
-// lockFunctionFacts apply on every method.
-type lockFunctionFacts struct {
-	// GuardedBy tracks the names and number of parameter (including receiver)
-	// lockFuncfields that guard calls to this function.
-	// The key is the name specified in the checklocks annotation. e.g given
-	// the following code.
-	// ```
-	// type A struct {
-	//   mu sync.Mutex
-	//   a int
-	// }
-	//
-	// // +checklocks:a.mu
-	// func xyz(a *A) {..}
-	// ```
-	//
-	// '`+checklocks:a.mu' will result in an entry in this map as shown below.
-	// GuardedBy: {"a.mu" => {ParameterNumber: 0, FieldNumber: 0}
-	GuardedBy map[string]functionGuard
-}
-
-// AFact implements analysis.Fact.AFact.
-func (*lockFunctionFacts) AFact() {}
-
-type positionKey string
-
-// toPositionKey converts from a token.Position to a key we can use to track
-// failures as the position of the failure annotation is not the same as the
-// position of the actual failure (different column/offsets). Hence we ignore
-// these fields and only use the file/line numbers to track failures.
-func toPositionKey(position token.Position) positionKey {
-	return positionKey(fmt.Sprintf("%s:%d", position.Filename, position.Line))
-}
-
-type failData struct {
-	pos   token.Pos
-	count int
-}
-
-func (f failData) String() string {
-	return fmt.Sprintf("pos: %d, count: %d", f.pos, f.count)
+	FactTypes: []analysis.Fact{(*atomicAlignment)(nil), (*lockFieldFacts)(nil), (*lockGuardFacts)(nil), (*lockFunctionFacts)(nil)},
 }
 
+// passContext is a pass with additional expected failures.
 type passContext struct {
-	pass *analysis.Pass
-
-	// exemptions tracks functions that should be exempted from lock checking due
-	// to '// +checklocksignore' annotation.
-	exemptions map[types.Object]struct{}
-
-	failures map[positionKey]*failData
+	pass       *analysis.Pass
+	failures   map[positionKey]*failData
+	exemptions map[positionKey]struct{}
+	forced     map[positionKey]struct{}
+	functions  map[*ssa.Function]struct{}
 }
 
-var (
-	mutexRE   = regexp.MustCompile("((.*/)|^)sync.(CrossGoroutineMutex|Mutex)")
-	rwMutexRE = regexp.MustCompile("((.*/)|^)sync.(CrossGoroutineRWMutex|RWMutex)")
-)
-
-func (pc *passContext) extractFieldAnnotations(field *ast.Field, fieldType *types.Var) *lockFieldFacts {
-	s := fieldType.Type().String()
-	// We use HasSuffix below because fieldType can be fully qualified with the
-	// package name eg for the gvisor sync package mutex fields have the type:
-	// "<package path>/sync/sync.Mutex"
-	switch {
-	case mutexRE.Match([]byte(s)):
-		return &lockFieldFacts{IsMutex: true}
-	case rwMutexRE.Match([]byte(s)):
-		return &lockFieldFacts{IsRWMutex: true}
-	default:
-	}
-	if field.Doc == nil {
-		return nil
-	}
-	fieldFacts := &lockFieldFacts{GuardedBy: make(map[string]int)}
-	for _, l := range field.Doc.List {
-		if strings.HasPrefix(l.Text, checkLocksAnnotation) {
-			guardName := strings.TrimPrefix(l.Text, checkLocksAnnotation)
-			if _, ok := fieldFacts.GuardedBy[guardName]; ok {
-				pc.pass.Reportf(field.Pos(), "annotation %s specified more than once.", l.Text)
-				continue
-			}
-			fieldFacts.GuardedBy[guardName] = -1
-		}
-	}
-
-	return fieldFacts
-}
-
-func (pc *passContext) findField(v ssa.Value, fieldNumber int) types.Object {
-	structType, ok := v.Type().Underlying().(*types.Struct)
-	if !ok {
-		structType = v.Type().Underlying().(*types.Pointer).Elem().Underlying().(*types.Struct)
-	}
-	return structType.Field(fieldNumber)
-}
-
-// findAndExportStructFacts finds any struct fields that are annotated with the
-// "// +checklocks:" annotation and exports relevant facts about the fields to
-// be used in later analysis.
-func (pc *passContext) findAndExportStructFacts(ss *ast.StructType, structType *types.Struct) {
-	type fieldRef struct {
-		fieldObj *types.Var
-		facts    *lockFieldFacts
-	}
-	mutexes := make(map[string]*fieldRef)
-	rwMutexes := make(map[string]*fieldRef)
-	guardedFields := make(map[string]*fieldRef)
-	for i, field := range ss.Fields.List {
-		fieldObj := structType.Field(i)
-		fieldFacts := pc.extractFieldAnnotations(field, fieldObj)
-		if fieldFacts == nil {
-			continue
-		}
-		fieldFacts.FieldNumber = i
-
-		ref := &fieldRef{fieldObj, fieldFacts}
-		if fieldFacts.IsMutex {
-			mutexes[fieldObj.Name()] = ref
-		}
-		if fieldFacts.IsRWMutex {
-			rwMutexes[fieldObj.Name()] = ref
-		}
-		if len(fieldFacts.GuardedBy) != 0 {
-			guardedFields[fieldObj.Name()] = ref
-		}
-	}
-
-	// Export facts about all mutexes.
-	for _, f := range mutexes {
-		pc.pass.ExportObjectFact(f.fieldObj, f.facts)
-	}
-	// Export facts about all rwMutexes.
-	for _, f := range rwMutexes {
-		pc.pass.ExportObjectFact(f.fieldObj, f.facts)
-	}
-
-	// Validate that guarded fields annotations refer to actual mutexes or
-	// rwMutexes in the struct.
-	for _, gf := range guardedFields {
-		for g := range gf.facts.GuardedBy {
-			if f, ok := mutexes[g]; ok {
-				gf.facts.GuardedBy[g] = f.facts.FieldNumber
-			} else if f, ok := rwMutexes[g]; ok {
-				gf.facts.GuardedBy[g] = f.facts.FieldNumber
-			} else {
-				pc.maybeFail(gf.fieldObj.Pos(), false /* isExempted */, "invalid mutex guard, no such mutex %s in struct %s", g, structType.String())
-				continue
-			}
-			// Export guarded field fact.
-			pc.pass.ExportObjectFact(gf.fieldObj, gf.facts)
-		}
-	}
-}
-
-func (pc *passContext) findAndExportFuncFacts(d *ast.FuncDecl) {
-	log.Debugf("finding and exporting function facts\n")
-	// for each function definition, check for +checklocks:mu annotation, which
-	// means that the function must be called with that lock held.
-	fnObj := pc.pass.TypesInfo.ObjectOf(d.Name)
-	funcFacts := lockFunctionFacts{GuardedBy: make(map[string]functionGuard)}
-	var (
-		ignore    bool
-		ignorePos token.Pos
-	)
-
-outerLoop:
-	for _, l := range d.Doc.List {
-		if strings.HasPrefix(l.Text, checkLocksIgnore) {
-			pc.exemptions[fnObj] = struct{}{}
-			ignore = true
-			ignorePos = l.Pos()
-			continue
-		}
-		if strings.HasPrefix(l.Text, checkLocksAnnotation) {
-			guardName := strings.TrimPrefix(l.Text, checkLocksAnnotation)
-			if _, ok := funcFacts.GuardedBy[guardName]; ok {
-				pc.pass.Reportf(l.Pos(), "annotation %s specified more than once.", l.Text)
-				continue
-			}
-
-			found := false
-			x := strings.Split(guardName, ".")
-			if len(x) != 2 {
-				pc.pass.Reportf(l.Pos(), "checklocks mutex annotation should be of the form 'a.b'")
+// forAllTypes applies the given function over all types.
+func (pc *passContext) forAllTypes(fn func(ts *ast.TypeSpec)) {
+	for _, f := range pc.pass.Files {
+		for _, decl := range f.Decls {
+			d, ok := decl.(*ast.GenDecl)
+			if !ok || d.Tok != token.TYPE {
 				continue
 			}
-			paramName, fieldName := x[0], x[1]
-			log.Debugf("paramName: %s, fieldName: %s", paramName, fieldName)
-			var paramList []*ast.Field
-			if d.Recv != nil {
-				paramList = append(paramList, d.Recv.List...)
-			}
-			if d.Type.Params != nil {
-				paramList = append(paramList, d.Type.Params.List...)
-			}
-			for paramNum, field := range paramList {
-				log.Debugf("field names: %+v", field.Names)
-				if len(field.Names) == 0 {
-					log.Debugf("skipping because parameter is unnamed", paramName)
-					continue
-				}
-				nameExists := false
-				for _, name := range field.Names {
-					if name.Name == paramName {
-						nameExists = true
-					}
-				}
-				if !nameExists {
-					log.Debugf("skipping because parameter name(s) does not match : %s", paramName)
-					continue
-				}
-				ptrType, ok := pc.pass.TypesInfo.TypeOf(field.Type).Underlying().(*types.Pointer)
-				if !ok {
-					// Since mutexes cannot be copied we only care about parameters that
-					// are pointer types when checking for guards.
-					pc.pass.Reportf(l.Pos(), "annotation %s incorrectly specified, parameter name does not refer to a pointer type", l.Text)
-					continue outerLoop
-				}
-
-				structType, ok := ptrType.Elem().Underlying().(*types.Struct)
-				if !ok {
-					pc.pass.Reportf(l.Pos(), "annotation %s incorrectly specified, parameter name does not refer to a pointer to a struct", l.Text)
-					continue outerLoop
-				}
-
-				for i := 0; i < structType.NumFields(); i++ {
-					if structType.Field(i).Name() == fieldName {
-						var fieldFacts lockFieldFacts
-						pc.pass.ImportObjectFact(structType.Field(i), &fieldFacts)
-						if !fieldFacts.IsMutex && !fieldFacts.IsRWMutex {
-							pc.pass.Reportf(l.Pos(), "field %s of param %s is not a mutex or an rwmutex", paramName, structType.Field(i))
-							continue outerLoop
-						}
-						funcFacts.GuardedBy[guardName] = functionGuard{ParameterNumber: paramNum, FieldNumber: i}
-						found = true
-						continue outerLoop
-					}
-				}
-				if !found {
-					pc.pass.Reportf(l.Pos(), "annotation refers to a non-existent field %s in %s", guardName, structType)
-					continue outerLoop
-				}
-			}
-			if !found {
-				pc.pass.Reportf(l.Pos(), "annotation refers to a non-existent parameter %s", paramName)
-			}
-		}
-	}
-
-	if len(funcFacts.GuardedBy) == 0 {
-		return
-	}
-	if ignore {
-		pc.pass.Reportf(ignorePos, "//+checklocksignore cannot be specified with other annotations on the function")
-	}
-	funcObj, ok := pc.pass.TypesInfo.Defs[d.Name].(*types.Func)
-	if !ok {
-		panic(fmt.Sprintf("function type information missing for %+v", d))
-	}
-	log.Debugf("export fact for d: %+v, funcObj: %+v, funcFacts: %+v\n", d, funcObj, funcFacts)
-	pc.pass.ExportObjectFact(funcObj, &funcFacts)
-}
-
-type mutexState struct {
-	// lockedMutexes is used to track which mutexes in a given struct are
-	// currently locked using the field number of the mutex as the key.
-	lockedMutexes map[int]struct{}
-}
-
-// locksHeld tracks all currently held locks.
-type locksHeld struct {
-	locks map[ssa.Value]mutexState
-}
-
-// Same returns true if the locks held by other and l are the same.
-func (l *locksHeld) Same(other *locksHeld) bool {
-	return reflect.DeepEqual(l.locks, other.locks)
-}
-
-// Copy creates a copy of all the lock state held by l.
-func (l *locksHeld) Copy() *locksHeld {
-	out := &locksHeld{locks: make(map[ssa.Value]mutexState)}
-	for ssaVal, mState := range l.locks {
-		newLM := make(map[int]struct{})
-		for k, v := range mState.lockedMutexes {
-			newLM[k] = v
-		}
-		out.locks[ssaVal] = mutexState{lockedMutexes: newLM}
-	}
-	return out
-}
-
-func isAlias(first, second ssa.Value) bool {
-	if first == second {
-		return true
-	}
-	switch x := first.(type) {
-	case *ssa.Field:
-		if y, ok := second.(*ssa.Field); ok {
-			return x.Field == y.Field && isAlias(x.X, y.X)
-		}
-	case *ssa.FieldAddr:
-		if y, ok := second.(*ssa.FieldAddr); ok {
-			return x.Field == y.Field && isAlias(x.X, y.X)
-		}
-	case *ssa.Index:
-		if y, ok := second.(*ssa.Index); ok {
-			return isAlias(x.Index, y.Index) && isAlias(x.X, y.X)
-		}
-	case *ssa.IndexAddr:
-		if y, ok := second.(*ssa.IndexAddr); ok {
-			return isAlias(x.Index, y.Index) && isAlias(x.X, y.X)
-		}
-	case *ssa.UnOp:
-		if y, ok := second.(*ssa.UnOp); ok {
-			return isAlias(x.X, y.X)
-		}
-	}
-	return false
-}
-
-// checkBasicBlocks traverses the control flow graph starting at a set of given
-// block and checks each instruction for allowed operations.
-//
-// funcFact are the exported facts for the enclosing function for these basic
-// blocks.
-func (pc *passContext) checkBasicBlocks(blocks []*ssa.BasicBlock, recoverBlock *ssa.BasicBlock, fn *ssa.Function, funcFact lockFunctionFacts) {
-	if len(blocks) == 0 {
-		return
-	}
-
-	// mutexes is used to track currently locked sync.Mutexes/sync.RWMutexes for a
-	// given *struct identified by ssa.Value.
-	seen := make(map[*ssa.BasicBlock]*locksHeld)
-	var scan func(block *ssa.BasicBlock, parent *locksHeld)
-	scan = func(block *ssa.BasicBlock, parent *locksHeld) {
-		_, isExempted := pc.exemptions[block.Parent().Object()]
-		if oldLocksHeld, ok := seen[block]; ok {
-			if oldLocksHeld.Same(parent) {
-				return
-			}
-			pc.maybeFail(block.Instrs[0].Pos(), isExempted, "failure entering a block %+v with different sets of lock held, oldLocks: %+v, parentLocks: %+v", block, oldLocksHeld, parent)
-			return
-		}
-		seen[block] = parent
-		var lh = parent.Copy()
-		for _, inst := range block.Instrs {
-			pc.checkInstruction(inst, isExempted, lh)
-		}
-		for _, b := range block.Succs {
-			scan(b, lh)
-		}
-	}
-
-	// Initialize lh with any preconditions that require locks to be held for the
-	// method to be invoked.
-	lh := &locksHeld{locks: make(map[ssa.Value]mutexState)}
-	for _, fg := range funcFact.GuardedBy {
-		// The first is the method object itself so we skip that when looking
-		// for receiver/function parameters.
-		log.Debugf("fn: %s, fn.Operands() == %+v", fn, fn.Operands(nil))
-		r := fn.Params[fg.ParameterNumber]
-		guardObj := findField(r, fg.FieldNumber)
-		var fieldFacts lockFieldFacts
-		pc.pass.ImportObjectFact(guardObj, &fieldFacts)
-		if fieldFacts.IsMutex || fieldFacts.IsRWMutex {
-			m, ok := lh.locks[r]
-			if !ok {
-				m = mutexState{lockedMutexes: make(map[int]struct{})}
-				lh.locks[r] = m
+			for _, gs := range d.Specs {
+				fn(gs.(*ast.TypeSpec))
 			}
-			m.lockedMutexes[fieldFacts.FieldNumber] = struct{}{}
-		} else {
-			panic(fmt.Sprintf("function: %+v has an invalid guard that is not a mutex: %+v", fn, guardObj))
-		}
-	}
-
-	// Start scanning from the first basic block.
-	scan(blocks[0], lh)
-
-	// Validate that all blocks were touched.
-	for _, b := range blocks {
-		if _, ok := seen[b]; !ok && b != recoverBlock {
-			panic(fmt.Sprintf("block %+v was not visited during checkBasicBlocks", b))
-		}
-	}
-}
-
-func (pc *passContext) checkInstruction(inst ssa.Instruction, isExempted bool, lh *locksHeld) {
-	log.Debugf("checking instruction: %s, isExempted: %t", inst, isExempted)
-	switch x := inst.(type) {
-	case *ssa.Field:
-		pc.checkFieldAccess(inst, x.X, x.Field, isExempted, lh)
-	case *ssa.FieldAddr:
-		pc.checkFieldAccess(inst, x.X, x.Field, isExempted, lh)
-	case *ssa.Call:
-		pc.checkFunctionCall(x, isExempted, lh)
-	}
-}
-
-func findField(v ssa.Value, field int) types.Object {
-	structType, ok := v.Type().Underlying().(*types.Struct)
-	if !ok {
-		ptrType, ok := v.Type().Underlying().(*types.Pointer)
-		if !ok {
-			return nil
-		}
-		structType = ptrType.Elem().Underlying().(*types.Struct)
-	}
-	return structType.Field(field)
-}
-
-func (pc *passContext) maybeFail(pos token.Pos, isExempted bool, fmtStr string, args ...interface{}) {
-	posKey := toPositionKey(pc.pass.Fset.Position(pos))
-	log.Debugf("maybeFail: pos: %d, positionKey: %s", pos, posKey)
-	if fData, ok := pc.failures[posKey]; ok {
-		fData.count--
-		if fData.count == 0 {
-			delete(pc.failures, posKey)
 		}
-		return
-	}
-	if !isExempted {
-		pc.pass.Reportf(pos, fmt.Sprintf(fmtStr, args...))
 	}
 }
 
-func (pc *passContext) checkFieldAccess(inst ssa.Instruction, structObj ssa.Value, field int, isExempted bool, lh *locksHeld) {
-	var fieldFacts lockFieldFacts
-	fieldObj := findField(structObj, field)
-	pc.pass.ImportObjectFact(fieldObj, &fieldFacts)
-	log.Debugf("fieldObj: %s, fieldFacts: %+v", fieldObj, fieldFacts)
-	for _, guardFieldNumber := range fieldFacts.GuardedBy {
-		guardObj := findField(structObj, guardFieldNumber)
-		var guardfieldFacts lockFieldFacts
-		pc.pass.ImportObjectFact(guardObj, &guardfieldFacts)
-		log.Debugf("guardObj: %s, guardFieldFacts: %+v", guardObj, guardfieldFacts)
-		if guardfieldFacts.IsMutex || guardfieldFacts.IsRWMutex {
-			log.Debugf("guard is a mutex")
-			m, ok := lh.locks[structObj]
+// forAllFunctions applies the given function over all functions.
+func (pc *passContext) forAllFunctions(fn func(fn *ast.FuncDecl)) {
+	for _, f := range pc.pass.Files {
+		for _, decl := range f.Decls {
+			d, ok := decl.(*ast.FuncDecl)
 			if !ok {
-				pc.maybeFail(inst.Pos(), isExempted, "invalid field access, %s must be locked when accessing %s", guardObj.Name(), fieldObj.Name())
-				continue
-			}
-			if _, ok := m.lockedMutexes[guardfieldFacts.FieldNumber]; !ok {
-				pc.maybeFail(inst.Pos(), isExempted, "invalid field access, %s must be locked when accessing %s", guardObj.Name(), fieldObj.Name())
-			}
-		} else {
-			panic("incorrect guard that is not a mutex or an RWMutex")
-		}
-	}
-}
-
-func (pc *passContext) checkFunctionCall(call *ssa.Call, isExempted bool, lh *locksHeld) {
-	// See: https://godoc.org/golang.org/x/tools/go/ssa#CallCommon
-	//
-	// 1. "call" mode: when Method is nil (!IsInvoke), a CallCommon represents an ordinary
-	//  function call of the value in Value, which may be a *Builtin, a *Function or any
-	//  other value of kind 'func'.
-	//
-	// 	Value may be one of:
-	// (a) a *Function, indicating a statically dispatched call
-	// to a package-level function, an anonymous function, or
-	// a method of a named type.
-	//
-	// (b) a *MakeClosure, indicating an immediately applied
-	// function literal with free variables.
-	//
-	// (c) a *Builtin, indicating a statically dispatched call
-	// to a built-in function.
-	//
-	// (d) any other value, indicating a dynamically dispatched
-	//     function call.
-	fn, ok := call.Common().Value.(*ssa.Function)
-	if !ok {
-		return
-	}
-	if fn.Object() == nil {
-		return
-	}
-
-	// Check if the function should be called with any locks held.
-	var funcFact lockFunctionFacts
-	pc.pass.ImportObjectFact(fn.Object(), &funcFact)
-	if len(funcFact.GuardedBy) > 0 {
-		for _, fg := range funcFact.GuardedBy {
-			// The first is the method object itself so we skip that when looking
-			// for receiver/function parameters.
-			r := (*call.Value().Operands(nil)[fg.ParameterNumber+1])
-			guardObj := findField(r, fg.FieldNumber)
-			if guardObj == nil {
 				continue
 			}
-			var fieldFacts lockFieldFacts
-			pc.pass.ImportObjectFact(guardObj, &fieldFacts)
-			if fieldFacts.IsMutex || fieldFacts.IsRWMutex {
-				heldMutexes, ok := lh.locks[r]
-				if !ok {
-					log.Debugf("fn: %s, funcFact: %+v", fn, funcFact)
-					pc.maybeFail(call.Pos(), isExempted, "invalid function call %s must be held", guardObj.Name())
-					continue
-				}
-				if _, ok := heldMutexes.lockedMutexes[fg.FieldNumber]; !ok {
-					log.Debugf("fn: %s, funcFact: %+v", fn, funcFact)
-					pc.maybeFail(call.Pos(), isExempted, "invalid function call %s must be held", guardObj.Name())
-				}
-			} else {
-				panic(fmt.Sprintf("function: %+v has an invalid guard that is not a mutex: %+v", fn, guardObj))
-			}
-		}
-	}
-
-	// Check if it's a method dispatch for something in the sync package.
-	// See: https://godoc.org/golang.org/x/tools/go/ssa#Function
-	if fn.Package() != nil && fn.Package().Pkg.Name() == "sync" && fn.Signature.Recv() != nil {
-		r, ok := call.Common().Args[0].(*ssa.FieldAddr)
-		if !ok {
-			return
-		}
-		guardObj := findField(r.X, r.Field)
-		var fieldFacts lockFieldFacts
-		pc.pass.ImportObjectFact(guardObj, &fieldFacts)
-		if fieldFacts.IsMutex || fieldFacts.IsRWMutex {
-			switch fn.Name() {
-			case "Lock", "RLock":
-				obj := r.X
-				m := mutexState{lockedMutexes: make(map[int]struct{})}
-				for k, v := range lh.locks {
-					if isAlias(r.X, k) {
-						obj = k
-						m = v
-					}
-				}
-				if _, ok := m.lockedMutexes[r.Field]; ok {
-					// Double locking a mutex that is already locked.
-					pc.maybeFail(call.Pos(), isExempted, "trying to a lock %s when already locked", guardObj.Name())
-					return
-				}
-				m.lockedMutexes[r.Field] = struct{}{}
-				lh.locks[obj] = m
-			case "Unlock", "RUnlock":
-				// Find the associated locker object.
-				var (
-					obj ssa.Value
-					m   mutexState
-				)
-				for k, v := range lh.locks {
-					if isAlias(r.X, k) {
-						obj = k
-						m = v
-						break
-					}
-				}
-				if _, ok := m.lockedMutexes[r.Field]; !ok {
-					pc.maybeFail(call.Pos(), isExempted, "trying to unlock a mutex %s that is already unlocked", guardObj.Name())
-					return
-				}
-				delete(m.lockedMutexes, r.Field)
-				if len(m.lockedMutexes) == 0 {
-					delete(lh.locks, obj)
-				}
-			case "RLocker", "DowngradeLock", "TryLock", "TryRLock":
-				// we explicitly ignore this for now.
-			default:
-				panic(fmt.Sprintf("unexpected mutex/rwmutex method invoked: %s", fn.Name()))
-			}
+			fn(d)
 		}
 	}
 }
 
+// run is the main entrypoint.
 func run(pass *analysis.Pass) (interface{}, error) {
 	pc := &passContext{
 		pass:       pass,
-		exemptions: make(map[types.Object]struct{}),
 		failures:   make(map[positionKey]*failData),
+		exemptions: make(map[positionKey]struct{}),
+		forced:     make(map[positionKey]struct{}),
+		functions:  make(map[*ssa.Function]struct{}),
 	}
 
 	// Find all line failure annotations.
-	for _, f := range pass.Files {
-		for _, cg := range f.Comments {
-			for _, c := range cg.List {
-				if strings.Contains(c.Text, checkLocksFail) {
-					cnt := 1
-					if strings.Contains(c.Text, checkLocksFail+":") {
-						parts := strings.SplitAfter(c.Text, checkLocksFail+":")
-						parsedCount, err := strconv.Atoi(parts[1])
-						if err != nil {
-							pc.pass.Reportf(c.Pos(), "invalid checklocks annotation : %s", err)
-							continue
-						}
-						cnt = parsedCount
-					}
-					position := toPositionKey(pass.Fset.Position(c.Pos()))
-					pc.failures[position] = &failData{pos: c.Pos(), count: cnt}
-				}
-			}
-		}
-	}
-
-	// Find all struct declarations and export any relevant facts.
-	for _, f := range pass.Files {
-		for _, decl := range f.Decls {
-			d, ok := decl.(*ast.GenDecl)
-			// A GenDecl node (generic declaration node) represents an import,
-			// constant, type or variable declaration.  We only care about struct
-			// declarations so skip any declaration that doesn't declare a new type.
-			if !ok || d.Tok != token.TYPE {
-				continue
-			}
+	pc.extractLineFailures()
 
-			for _, gs := range d.Specs {
-				ts := gs.(*ast.TypeSpec)
-				ss, ok := ts.Type.(*ast.StructType)
-				if !ok {
-					continue
-				}
-				structType := pass.TypesInfo.TypeOf(ts.Name).Underlying().(*types.Struct)
-				pc.findAndExportStructFacts(ss, structType)
-			}
+	// Find all struct declarations and export relevant facts.
+	pc.forAllTypes(func(ts *ast.TypeSpec) {
+		if ss, ok := ts.Type.(*ast.StructType); ok {
+			pc.exportLockFieldFacts(ts, ss)
 		}
-	}
+	})
+	pc.forAllTypes(func(ts *ast.TypeSpec) {
+		if ss, ok := ts.Type.(*ast.StructType); ok {
+			pc.exportLockGuardFacts(ts, ss)
+		}
+	})
 
-	// Find all method calls and export any relevant facts.
-	for _, f := range pass.Files {
-		for _, decl := range f.Decls {
-			d, ok := decl.(*ast.FuncDecl)
-			// Ignore any non function declarations and any functions that do not have
-			// any comments.
-			if !ok || d.Doc == nil {
-				continue
-			}
-			pc.findAndExportFuncFacts(d)
+	// Check all alignments.
+	pc.forAllTypes(func(ts *ast.TypeSpec) {
+		typ, ok := pass.TypesInfo.TypeOf(ts.Name).(*types.Named)
+		if !ok {
+			return
 		}
-	}
+		pc.checkTypeAlignment(pass.Pkg, typ)
+	})
 
-	// log all known facts and all failures if debug logging is enabled.
-	allFacts := pass.AllObjectFacts()
-	for i := range allFacts {
-		log.Debugf("fact.object: %+v, fact.Fact: %+v", allFacts[i].Object, allFacts[i].Fact)
-	}
-	log.Debugf("all expected failures: %+v", pc.failures)
+	// Find all function declarations and export relevant facts.
+	pc.forAllFunctions(func(fn *ast.FuncDecl) {
+		pc.exportFunctionFacts(fn)
+	})
 
 	// Scan all code looking for invalid accesses.
 	state := pass.ResultOf[buildssa.Analyzer].(*buildssa.SSA)
 	for _, fn := range state.SrcFuncs {
-		var funcFact lockFunctionFacts
-		// Anonymous(closures) functions do not have an object() but do show up in
-		// the SSA.
-		if obj := fn.Object(); obj != nil {
-			pc.pass.ImportObjectFact(fn.Object(), &funcFact)
+		// Import function facts generated above.
+		//
+		// Note that anonymous(closures) functions do not have an
+		// object but do show up in the SSA. They can only be invoked
+		// by named functions in the package, and they are analyzing
+		// inline on every call. Thus we skip the analysis here. They
+		// will be hit on calls, or picked up in the pass below.
+		if obj := fn.Object(); obj == nil {
+			continue
 		}
+		var lff lockFunctionFacts
+		pc.pass.ImportObjectFact(fn.Object(), &lff)
 
-		log.Debugf("checking function: %s", fn)
-		var b bytes.Buffer
-		ssa.WriteFunction(&b, fn)
-		log.Debugf("function SSA: %s", b.String())
-		if fn.Recover != nil {
-			pc.checkBasicBlocks([]*ssa.BasicBlock{fn.Recover}, nil, fn, funcFact)
+		// Do we ignore this?
+		if lff.Ignore {
+			continue
 		}
-		pc.checkBasicBlocks(fn.Blocks, fn.Recover, fn, funcFact)
-	}
 
-	// Scan for remaining failures we expect.
-	for _, failure := range pc.failures {
-		// We are missing expect failures, report as much as possible.
-		pass.Reportf(failure.pos, "expected %d failures", failure.count)
+		// Check the basic blocks in the function.
+		pc.checkFunction(nil, fn, &lff, nil, false /* force */)
 	}
+	for _, fn := range state.SrcFuncs {
+		// Ensure all anonymous functions are hit. They are not
+		// permitted to have any lock preconditions.
+		if obj := fn.Object(); obj != nil {
+			continue
+		}
+		var nolff lockFunctionFacts
+		pc.checkFunction(nil, fn, &nolff, nil, false /* force */)
+	}
+
+	// Check for expected failures.
+	pc.checkFailures()
 
 	return nil, nil
 }