Source file src/cmd/vendor/golang.org/x/tools/go/analysis/passes/loopclosure/doc.go

     1  // Copyright 2023 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package loopclosure defines an Analyzer that checks for references to
     6  // enclosing loop variables from within nested functions.
     7  //
     8  // # Analyzer loopclosure
     9  //
    10  // loopclosure: check references to loop variables from within nested functions
    11  //
    12  // This analyzer reports places where a function literal references the
    13  // iteration variable of an enclosing loop, and the loop calls the function
    14  // in such a way (e.g. with go or defer) that it may outlive the loop
    15  // iteration and possibly observe the wrong value of the variable.
    16  //
    17  // Note: An iteration variable can only outlive a loop iteration in Go versions <=1.21.
    18  // In Go 1.22 and later, the loop variable lifetimes changed to create a new
    19  // iteration variable per loop iteration. (See go.dev/issue/60078.)
    20  //
    21  // In this example, all the deferred functions run after the loop has
    22  // completed, so all observe the final value of v [<go1.22].
    23  //
    24  //	for _, v := range list {
    25  //	    defer func() {
    26  //	        use(v) // incorrect
    27  //	    }()
    28  //	}
    29  //
    30  // One fix is to create a new variable for each iteration of the loop:
    31  //
    32  //	for _, v := range list {
    33  //	    v := v // new var per iteration
    34  //	    defer func() {
    35  //	        use(v) // ok
    36  //	    }()
    37  //	}
    38  //
    39  // After Go version 1.22, the previous two for loops are equivalent
    40  // and both are correct.
    41  //
    42  // The next example uses a go statement and has a similar problem [<go1.22].
    43  // In addition, it has a data race because the loop updates v
    44  // concurrent with the goroutines accessing it.
    45  //
    46  //	for _, v := range elem {
    47  //	    go func() {
    48  //	        use(v)  // incorrect, and a data race
    49  //	    }()
    50  //	}
    51  //
    52  // A fix is the same as before. The checker also reports problems
    53  // in goroutines started by golang.org/x/sync/errgroup.Group.
    54  // A hard-to-spot variant of this form is common in parallel tests:
    55  //
    56  //	func Test(t *testing.T) {
    57  //	    for _, test := range tests {
    58  //	        t.Run(test.name, func(t *testing.T) {
    59  //	            t.Parallel()
    60  //	            use(test) // incorrect, and a data race
    61  //	        })
    62  //	    }
    63  //	}
    64  //
    65  // The t.Parallel() call causes the rest of the function to execute
    66  // concurrent with the loop [<go1.22].
    67  //
    68  // The analyzer reports references only in the last statement,
    69  // as it is not deep enough to understand the effects of subsequent
    70  // statements that might render the reference benign.
    71  // ("Last statement" is defined recursively in compound
    72  // statements such as if, switch, and select.)
    73  //
    74  // See: https://golang.org/doc/go_faq.html#closures_and_goroutines
    75  package loopclosure
    76  

View as plain text