Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: fix type on gleak go doc #708

Merged
merged 1 commit into from
Oct 25, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 30 additions & 32 deletions gleak/doc.go
Original file line number Diff line number Diff line change
@@ -1,21 +1,20 @@
/*

package gleak complements the Gingko/Gomega testing and matchers framework with
matchers for Goroutine leakage detection.

Basics of nleak
# Basics of gleak

To start with,

Goroutines()
Goroutines()

returns information about all (non-dead) goroutines at a particular moment. This
is useful to capture a known correct snapshot and then later taking a new
snapshot and comparing these two snapshots for leaked goroutines.

Next, the matcher

HaveLeaked(...)
HaveLeaked(...)

filters out well-known and expected "non-leaky" goroutines from an actual list
of goroutines (passed from Eventually or Expect), hopefully ending up with an
Expand All @@ -26,67 +25,67 @@ because no one wants leaked goroutines.

A typical pattern to detect goroutines leaked in individual tests is as follows:

var ignoreGood []Goroutine
var ignoreGood []Goroutine

BeforeEach(func() {
ignoreGood = Goroutines()
})
BeforeEach(func() {
ignoreGood = Goroutines()
})

AfterEach(func() {
// Note: it's "Goroutines", but not "Goroutines()", when using with Eventually!
Eventually(Goroutines).ShouldNot(HaveLeaked(ignoreGood))
})
AfterEach(func() {
// Note: it's "Goroutines", but not "Goroutines()", when using with Eventually!
Eventually(Goroutines).ShouldNot(HaveLeaked(ignoreGood))
})

Using Eventually instead of Expect ensures that there is some time given for
temporary goroutines to finally wind down. Gomega's default values apply: the 1s
timeout and 10ms polling interval.

Please note that the form

HaveLeaked(ignoreGood)
HaveLeaked(ignoreGood)

is the same as the slightly longer, but also more expressive variant:

HaveLeaked(IgnoringGoroutines(ignoreGood))
HaveLeaked(IgnoringGoroutines(ignoreGood))

Leak-Related Matchers
# Leak-Related Matchers

Depending on your tests and the dependencies used, you might need to identify
additional goroutines as not being leaks. The gleak packages comes with the
following predefined goroutine "filter" matchers that can be specified as
arguments to HaveLeaked(...):

IgnoringTopFunction("foo.bar") // exactly "foo.bar"
IgnoringTopFunction("foo.bar...") // top function name with prefix "foo.bar." (note the trailing dot!)
IgnoringTopFunction("foo.bar [chan receive]") // exactly "foo.bar" with state starting with "chan receive"
IgnoringGoroutines(expectedGoroutines) // ignore specified goroutines with these IDs
IgnoringInBacktrace("foo.bar.baz") // "foo.bar.baz" within the backtrace
IgnoringCreator("foo.bar") // exact creator function name "foo.bar"
IgnoringCreator("foo.bar...") // creator function name with prefix "foo.bar."
IgnoringTopFunction("foo.bar") // exactly "foo.bar"
IgnoringTopFunction("foo.bar...") // top function name with prefix "foo.bar." (note the trailing dot!)
IgnoringTopFunction("foo.bar [chan receive]") // exactly "foo.bar" with state starting with "chan receive"
IgnoringGoroutines(expectedGoroutines) // ignore specified goroutines with these IDs
IgnoringInBacktrace("foo.bar.baz") // "foo.bar.baz" within the backtrace
IgnoringCreator("foo.bar") // exact creator function name "foo.bar"
IgnoringCreator("foo.bar...") // creator function name with prefix "foo.bar."

In addition, you can use any other GomegaMatcher, as long as it can work on a
(single) Goroutine. For instance, Gomega's HaveField and WithTransform
matchers are good foundations for writing project-specific gleak matchers.

Leaked Goroutine Dump
# Leaked Goroutine Dump

By default, when gleak's HaveLeaked matcher finds one or more leaked
goroutines, it dumps the goroutine backtraces in a condensed format that uses
only a single line per call instead of two lines. Moreover, the backtraces
abbreviate the source file location in the form of package/source.go:lineno:

goroutine 42 [flabbergasted]
main.foo.func1() at foo/test.go:6
created by main.foo at foo/test.go:5
goroutine 42 [flabbergasted]
main.foo.func1() at foo/test.go:6
created by main.foo at foo/test.go:5

By setting gleak.ReportFilenameWithPath=true the leaky goroutine backtraces
will show full path names for each source file:

goroutine 42 [flabbergasted]
main.foo.func1() at /home/go/foo/test.go:6
created by main.foo at home/go/foo/test.go:5
goroutine 42 [flabbergasted]
main.foo.func1() at /home/go/foo/test.go:6
created by main.foo at home/go/foo/test.go:5

Acknowledgement
# Acknowledgement

gleak has been heavily inspired by the Goroutine leak detector
github.com/uber-go/goleak. That's definitely a fine piece of work!
Expand All @@ -110,9 +109,8 @@ out the non-leaking (and therefore expected) goroutines, using a few filter
criteria. That is, a few new goroutine-related matchers. In this architecture,
even existing Gomega matchers can optionally be (re)used as the need arises.

References
# References

https://github.com/onsi/gomega and https://github.com/onsi/ginkgo.

*/
package gleak
Loading