options.go at 100c34b ⋅ uber-go/goleak

// Copyright (c) 2017 Uber Technologies, Inc.
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
// THE SOFTWARE.

package goleak

import (
	"strings"
	"time"

	"go.uber.org/goleak/internal/stack"
)

// Option lets users specify custom verifications.
type Option interface {
	apply(*opts)
}

// We retry up to 20 times if we can't find the goroutine that
// we are looking for. In between each attempt, we will sleep for
// a short while to let any running goroutines complete.
const _defaultRetries = 20

type opts struct {
	filters    []func(stack.Stack) bool
	maxRetries int
	maxSleep   time.Duration
}

// optionFunc lets us easily write options without a custom type.
type optionFunc func(*opts)

func (f optionFunc) apply(opts *opts) { f(opts) }

// IgnoreTopFunction ignores any goroutines where the specified function
// is at the top of the stack. The function name should be fully qualified,
// e.g., go.uber.org/goleak.IgnoreTopFunction
func IgnoreTopFunction(f string) Option {
	return addFilter(func(s stack.Stack) bool {
		return s.FirstFunction() == f
	})
}

// IgnoreCurrent records all current goroutines when the option is created, and ignores
// them in any future Find/Verify calls.
func IgnoreCurrent() Option {
	excludeIDSet := map[int]bool{}
	for _, s := range stack.All() {
		excludeIDSet[s.ID()] = true
	}
	return addFilter(func(s stack.Stack) bool {
		return excludeIDSet[s.ID()]
	})
}

func maxSleep(d time.Duration) Option {
	return optionFunc(func(opts *opts) {
		opts.maxSleep = d
	})
}

func addFilter(f func(stack.Stack) bool) Option {
	return optionFunc(func(opts *opts) {
		opts.filters = append(opts.filters, f)
	})
}

func buildOpts(options ...Option) *opts {
	opts := &opts{
		maxRetries: _defaultRetries,
		maxSleep:   100 * time.Millisecond,
	}
	opts.filters = append(opts.filters,
		isTestStack,
		isSyscallStack,
		isStdLibStack,
		isTraceStack,
	)
	for _, option := range options {
		option.apply(opts)
	}
	return opts
}

func (vo *opts) filter(s stack.Stack) bool {
	for _, filter := range vo.filters {
		if filter(s) {
			return true
		}
	}
	return false
}

func (vo *opts) retry(i int) bool {
	if i >= vo.maxRetries {
		return false
	}

	d := time.Duration(int(time.Microsecond) << uint(i))
	if d > vo.maxSleep {
		d = vo.maxSleep
	}
	time.Sleep(d)
	return true
}

// isTestStack is a default filter installed to automatically skip goroutines
// that the testing package runs while the user's tests are running.
func isTestStack(s stack.Stack) bool {
	// Until go1.7, the main goroutine ran RunTests, which started
	// the test in a separate goroutine and waited for that test goroutine
	// to end by waiting on a channel.
	// Since go1.7, a separate goroutine is started to wait for signals.
	// T.Parallel is for parallel tests, which are blocked until all serial
	// tests have run with T.Parallel at the top of the stack.
	switch s.FirstFunction() {
	case "testing.RunTests", "testing.(*T).Run", "testing.(*T).Parallel":
		// In pre1.7 and post-1.7, background goroutines started by the testing
		// package are blocked waiting on a channel.
		return strings.HasPrefix(s.State(), "chan receive")
	}
	return false
}

func isSyscallStack(s stack.Stack) bool {
	// Typically runs in the background when code uses CGo:
	// https://github.com/golang/go/issues/16714
	return s.FirstFunction() == "runtime.goexit" && strings.HasPrefix(s.State(), "syscall")
}

func isStdLibStack(s stack.Stack) bool {
	// Importing os/signal starts a background goroutine.
	// The name of the function at the top has changed between versions.
	if f := s.FirstFunction(); f == "os/signal.signal_recv" || f == "os/signal.loop" {
		return true
	}

	// Using signal.Notify will start a runtime goroutine.
	return strings.Contains(s.Full(), "runtime.ensureSigM")
}

func isTraceStack(s stack.Stack) bool {
	if f := s.FirstFunction(); f != "runtime.goparkunlock" {
		return false
	}

	return strings.Contains(s.Full(), "runtime.ReadTrace")
}

Read our documentation on viewing source code .

1		// Copyright (c) 2017 Uber Technologies, Inc.
2		//
3		// Permission is hereby granted, free of charge, to any person obtaining a copy
4		// of this software and associated documentation files (the "Software"), to deal
5		// in the Software without restriction, including without limitation the rights
6		// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7		// copies of the Software, and to permit persons to whom the Software is
8		// furnished to do so, subject to the following conditions:
9		//
10		// The above copyright notice and this permission notice shall be included in
11		// all copies or substantial portions of the Software.
12		//
13		// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14		// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15		// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16		// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17		// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18		// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
19		// THE SOFTWARE.
20
21		package goleak
22
23		import (
24		"strings"
25		"time"
26
27		"go.uber.org/goleak/internal/stack"
28		)
29
30		// Option lets users specify custom verifications.
31		type Option interface {
32		apply(*opts)
33		}
34
35		// We retry up to 20 times if we can't find the goroutine that
36		// we are looking for. In between each attempt, we will sleep for
37		// a short while to let any running goroutines complete.
38		const _defaultRetries = 20
39
40		type opts struct {
41		filters []func(stack.Stack) bool
42		maxRetries int
43		maxSleep time.Duration
44		}
45
46		// optionFunc lets us easily write options without a custom type.
47		type optionFunc func(*opts)
48
49	3	func (f optionFunc) apply(opts *opts) { f(opts) }
50
51		// IgnoreTopFunction ignores any goroutines where the specified function
52		// is at the top of the stack. The function name should be fully qualified,
53		// e.g., go.uber.org/goleak.IgnoreTopFunction
54	3	func IgnoreTopFunction(f string) Option {
55	3	return addFilter(func(s stack.Stack) bool {
56	3	return s.FirstFunction() == f
57	3	})
58		}
59
60		// IgnoreCurrent records all current goroutines when the option is created, and ignores
61		// them in any future Find/Verify calls.
62	3	func IgnoreCurrent() Option {
63	3	excludeIDSet := map[int]bool{}
64	3	for _, s := range stack.All() {
65	3	excludeIDSet[s.ID()] = true
66		}
67	3	return addFilter(func(s stack.Stack) bool {
68	3	return excludeIDSet[s.ID()]
69	3	})
70		}
71
72	3	func maxSleep(d time.Duration) Option {
73	3	return optionFunc(func(opts *opts) {
74	3	opts.maxSleep = d
75	3	})
76		}
77
78	3	func addFilter(f func(stack.Stack) bool) Option {
79	3	return optionFunc(func(opts *opts) {
80	3	opts.filters = append(opts.filters, f)
81	3	})
82		}
83
84	3	func buildOpts(options ...Option) *opts {
85	3	opts := &opts{
86	3	maxRetries: _defaultRetries,
87	3	maxSleep: 100 * time.Millisecond,
88		}
89	3	opts.filters = append(opts.filters,
90	3	isTestStack,
91	3	isSyscallStack,
92	3	isStdLibStack,
93	3	isTraceStack,
94	3	)
95	3	for _, option := range options {
96	3	option.apply(opts)
97		}
98	3	return opts
99		}
100
101	3	func (vo *opts) filter(s stack.Stack) bool {
102	3	for _, filter := range vo.filters {
103	3	if filter(s) {
104	3	return true
105		}
106		}
107	3	return false
108		}
109
110	3	func (vo *opts) retry(i int) bool {
111	3	if i >= vo.maxRetries {
112	3	return false
113		}
114
115	3	d := time.Duration(int(time.Microsecond) << uint(i))
116	3	if d > vo.maxSleep {
117	3	d = vo.maxSleep
118		}
119	3	time.Sleep(d)
120	3	return true
121		}
122
123		// isTestStack is a default filter installed to automatically skip goroutines
124		// that the testing package runs while the user's tests are running.
125	3	func isTestStack(s stack.Stack) bool {
126		// Until go1.7, the main goroutine ran RunTests, which started
127		// the test in a separate goroutine and waited for that test goroutine
128		// to end by waiting on a channel.
129		// Since go1.7, a separate goroutine is started to wait for signals.
130		// T.Parallel is for parallel tests, which are blocked until all serial
131		// tests have run with T.Parallel at the top of the stack.
132	3	switch s.FirstFunction() {
133	3	case "testing.RunTests", "testing.(T).Run", "testing.(T).Parallel":
134		// In pre1.7 and post-1.7, background goroutines started by the testing
135		// package are blocked waiting on a channel.
136	3	return strings.HasPrefix(s.State(), "chan receive")
137		}
138	3	return false
139		}
140
141	3	func isSyscallStack(s stack.Stack) bool {
142		// Typically runs in the background when code uses CGo:
143		// https://github.com/golang/go/issues/16714
144	3	return s.FirstFunction() == "runtime.goexit" && strings.HasPrefix(s.State(), "syscall")
145		}
146
147	3	func isStdLibStack(s stack.Stack) bool {
148		// Importing os/signal starts a background goroutine.
149		// The name of the function at the top has changed between versions.
150	3	if f := s.FirstFunction(); f == "os/signal.signal_recv" \|\| f == "os/signal.loop" {
151	3	return true
152		}
153
154		// Using signal.Notify will start a runtime goroutine.
155	3	return strings.Contains(s.Full(), "runtime.ensureSigM")
156		}
157
158	3	func isTraceStack(s stack.Stack) bool {
159	3	if f := s.FirstFunction(); f != "runtime.goparkunlock" {
160	3	return false
161		}
162
163	2	return strings.Contains(s.Full(), "runtime.ReadTrace")
164		}

Navigation	Overlay
`t` Navigate files	`h` Toggle hits
`y` Change url to tip of branch	`m` Toggle misses
`b / v` Jump to prev/next hit line	`p` Toggle partial
`z / x` Jump to prev/next missed or partial line	`1..9` Toggle flags
`shift + o` Open current page in GitHub	`a` Toggle all on
`/ or ?` Show keyboard shortcuts dialog	`c` Toggle context lines or commits

Motivation