Skip to content

Commit f1b8343

Browse files
thediveoonsi
authored andcommittedOct 25, 2023
doc: fix type on gleak go doc
Signed-off-by: thediveo <thediveo@gmx.eu>
1 parent b94b195 commit f1b8343

File tree

1 file changed

+30
-32
lines changed

1 file changed

+30
-32
lines changed
 

‎gleak/doc.go

+30-32
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,20 @@
11
/*
2-
32
package gleak complements the Gingko/Gomega testing and matchers framework with
43
matchers for Goroutine leakage detection.
54
6-
Basics of nleak
5+
# Basics of gleak
76
87
To start with,
98
10-
Goroutines()
9+
Goroutines()
1110
1211
returns information about all (non-dead) goroutines at a particular moment. This
1312
is useful to capture a known correct snapshot and then later taking a new
1413
snapshot and comparing these two snapshots for leaked goroutines.
1514
1615
Next, the matcher
1716
18-
HaveLeaked(...)
17+
HaveLeaked(...)
1918
2019
filters out well-known and expected "non-leaky" goroutines from an actual list
2120
of goroutines (passed from Eventually or Expect), hopefully ending up with an
@@ -26,67 +25,67 @@ because no one wants leaked goroutines.
2625
2726
A typical pattern to detect goroutines leaked in individual tests is as follows:
2827
29-
var ignoreGood []Goroutine
28+
var ignoreGood []Goroutine
3029
31-
BeforeEach(func() {
32-
ignoreGood = Goroutines()
33-
})
30+
BeforeEach(func() {
31+
ignoreGood = Goroutines()
32+
})
3433
35-
AfterEach(func() {
36-
// Note: it's "Goroutines", but not "Goroutines()", when using with Eventually!
37-
Eventually(Goroutines).ShouldNot(HaveLeaked(ignoreGood))
38-
})
34+
AfterEach(func() {
35+
// Note: it's "Goroutines", but not "Goroutines()", when using with Eventually!
36+
Eventually(Goroutines).ShouldNot(HaveLeaked(ignoreGood))
37+
})
3938
4039
Using Eventually instead of Expect ensures that there is some time given for
4140
temporary goroutines to finally wind down. Gomega's default values apply: the 1s
4241
timeout and 10ms polling interval.
4342
4443
Please note that the form
4544
46-
HaveLeaked(ignoreGood)
45+
HaveLeaked(ignoreGood)
4746
4847
is the same as the slightly longer, but also more expressive variant:
4948
50-
HaveLeaked(IgnoringGoroutines(ignoreGood))
49+
HaveLeaked(IgnoringGoroutines(ignoreGood))
5150
52-
Leak-Related Matchers
51+
# Leak-Related Matchers
5352
5453
Depending on your tests and the dependencies used, you might need to identify
5554
additional goroutines as not being leaks. The gleak packages comes with the
5655
following predefined goroutine "filter" matchers that can be specified as
5756
arguments to HaveLeaked(...):
5857
59-
IgnoringTopFunction("foo.bar") // exactly "foo.bar"
60-
IgnoringTopFunction("foo.bar...") // top function name with prefix "foo.bar." (note the trailing dot!)
61-
IgnoringTopFunction("foo.bar [chan receive]") // exactly "foo.bar" with state starting with "chan receive"
62-
IgnoringGoroutines(expectedGoroutines) // ignore specified goroutines with these IDs
63-
IgnoringInBacktrace("foo.bar.baz") // "foo.bar.baz" within the backtrace
64-
IgnoringCreator("foo.bar") // exact creator function name "foo.bar"
65-
IgnoringCreator("foo.bar...") // creator function name with prefix "foo.bar."
58+
IgnoringTopFunction("foo.bar") // exactly "foo.bar"
59+
IgnoringTopFunction("foo.bar...") // top function name with prefix "foo.bar." (note the trailing dot!)
60+
IgnoringTopFunction("foo.bar [chan receive]") // exactly "foo.bar" with state starting with "chan receive"
61+
IgnoringGoroutines(expectedGoroutines) // ignore specified goroutines with these IDs
62+
IgnoringInBacktrace("foo.bar.baz") // "foo.bar.baz" within the backtrace
63+
IgnoringCreator("foo.bar") // exact creator function name "foo.bar"
64+
IgnoringCreator("foo.bar...") // creator function name with prefix "foo.bar."
6665
6766
In addition, you can use any other GomegaMatcher, as long as it can work on a
6867
(single) Goroutine. For instance, Gomega's HaveField and WithTransform
6968
matchers are good foundations for writing project-specific gleak matchers.
7069
71-
Leaked Goroutine Dump
70+
# Leaked Goroutine Dump
7271
7372
By default, when gleak's HaveLeaked matcher finds one or more leaked
7473
goroutines, it dumps the goroutine backtraces in a condensed format that uses
7574
only a single line per call instead of two lines. Moreover, the backtraces
7675
abbreviate the source file location in the form of package/source.go:lineno:
7776
78-
goroutine 42 [flabbergasted]
79-
main.foo.func1() at foo/test.go:6
80-
created by main.foo at foo/test.go:5
77+
goroutine 42 [flabbergasted]
78+
main.foo.func1() at foo/test.go:6
79+
created by main.foo at foo/test.go:5
8180
8281
By setting gleak.ReportFilenameWithPath=true the leaky goroutine backtraces
8382
will show full path names for each source file:
8483
85-
goroutine 42 [flabbergasted]
86-
main.foo.func1() at /home/go/foo/test.go:6
87-
created by main.foo at home/go/foo/test.go:5
84+
goroutine 42 [flabbergasted]
85+
main.foo.func1() at /home/go/foo/test.go:6
86+
created by main.foo at home/go/foo/test.go:5
8887
89-
Acknowledgement
88+
# Acknowledgement
9089
9190
gleak has been heavily inspired by the Goroutine leak detector
9291
github.com/uber-go/goleak. That's definitely a fine piece of work!
@@ -110,9 +109,8 @@ out the non-leaking (and therefore expected) goroutines, using a few filter
110109
criteria. That is, a few new goroutine-related matchers. In this architecture,
111110
even existing Gomega matchers can optionally be (re)used as the need arises.
112111
113-
References
112+
# References
114113
115114
https://github.com/onsi/gomega and https://github.com/onsi/ginkgo.
116-
117115
*/
118116
package gleak

0 commit comments

Comments
 (0)
Please sign in to comment.