goroutine

Documentation

Overview

Package goroutine discovers and returns information about either all goroutines or only the caller's goroutine. Information provided by the Goroutine type consists of a unique ID, the state, the name of the topmost (most recent) function in the call stack and the full backtrace. For goroutines other than the main goroutine (the one with ID 1) the creating function as well as location (file name and line number) are additionally provided.

Index

• type Goroutine
  • func Current() Goroutine
  • func Goroutines() []Goroutine
  • func (g Goroutine) GomegaString() string
  • func (g Goroutine) String() string

Types

type Goroutine

type Goroutine struct {
	ID              uint64 // unique goroutine ID ("goid" in Go's runtime parlance)
	State           string // goroutine state, such as "running"
	TopFunction     string // topmost function on goroutine's stack
	CreatorFunction string // name of function creating this goroutine, if any
	BornAt          string // location where the goroutine was started from, if any; format "file-path:line-number"
	Backtrace       string // goroutine's backtrace (of the stack)
}

Goroutine represents information about a single goroutine, such as its unique ID, state, backtrace, creator, and more.

Go's runtime assigns unique IDs to goroutines, also called "goid" in Go runtime parlance. These IDs start with 1 for the main goroutine and only increase (unless you manage to create 2**64-2 goroutines during the lifetime of your tests so that the goids wrap around). Due to runtime-internal optimizations, not all IDs might be used, so that there might be gaps. But IDs are never reused, so they're fine as unique goroutine identities.

The size of a goidsis always 64bits, even on 32bit architectures (if you like, you might want to double-check for yourself in runtime/runtime2.go and runtime/proc.go).

A Goroutine's State field starts with one of the following strings:

• "idle"
• "runnable"
• "running"
• "syscall"
• ("waiting" ... see below)
• ("dead" ... these goroutines should never appear in dumps)
• "copystack"
• "preempted"
• ("???" ... something IS severely broken.)

In case a goroutine is in waiting state, the State field instead starts with one of the following strings, never showing a lonely "waiting" string, but rather one of the reasons for waiting:

• "chan receive"
• "chan send"
• "select"
• "sleep"
• "finalizer wait"
• ...quite some more waiting states.

The State description may next contain "(scan)", separated by a single blank from the preceding goroutine state text.

If a goroutine is blocked from more than at least a minute, then the state description next contains the string "X minutes", where X is the number of minutes blocked. This text is separated by a "," and a blank from the preceding information.

Finally, OS thread-locked goroutines finally contain "locked to thread" in their State description, again separated by a "," and a blank from the preceding information.

Please note that the State field never contains the opening and closing square brackets as used in plain stack dumps.

func Current

func Current() Goroutine

Current returns information about the current goroutine in which it is called. Please note that the topmost function name will always be runtime.Stack.

func Goroutines

func Goroutines() []Goroutine

Goroutines returns information about all goroutines.

func (Goroutine) GomegaString

func (g Goroutine) GomegaString() string

GomegaString returns the Gomega struct representation of a Goroutine, but without a potentially rather lengthy backtrace. This Gomega object value dumps getting happily truncated as to become more or less useless.

func (Goroutine) String

func (g Goroutine) String() string

String returns a short textual description of this goroutine, but without the potentially lengthy and ugly backtrace details.