snapshotgraph

type Analysis ¶

type Analysis struct {
	Graph      *Graph
	Goroutines []GoroutineReachability
	Globals    GlobalReachability

	Warnings []string
	Stats    Stats
}

Analysis is the full output of Build: a resolved object graph plus reachability sets and summary stats.

func Build(snap *heapsnapshot.HeapSnapshot, opts Options) (*Analysis, error)

type GlobalReachability ¶

type GlobalReachability struct {
	Roots     []RootRef
	Reachable map[ObjectID]struct{}
}

GlobalReachability is the reachability set rooted at process-wide roots: data, bss, otherroot, finalizer, queued_finalizer.

Reachable is populated by ComputeReachability, not Build.

type GoroutineReachability ¶

type GoroutineReachability struct {
	GoroutineID  uint64
	IsSystem     bool
	IsBackground bool
	Roots        []RootRef
	Reachable    map[ObjectID]struct{}
}

GoroutineReachability is the reachability set rooted at a single goroutine's stack roots.

IsSystem and IsBackground are forwarded from the parsed goroutine record. Runtime-internal goroutines (g0, GC workers, the finalizer goroutine, etc.) hold pointers into runtime metadata that can pollute per-goroutine attribution if folded into user-visible bubbles. Phase 4 keeps them in the analysis but tags them so later phases can filter.

Reachable is populated by ComputeReachability, not Build. Callers that only need a label-selected subset (e.g. /debug/memusage) can ignore it and walk the graph themselves from Roots.

type Graph ¶

type Graph struct {
	Objects []Object
	ByAddr  map[uint64]ObjectID
	// contains filtered or unexported fields
}

Graph holds the compact process-wide object graph.

func (g *Graph) FindObjectContaining(ptr uint64) (ObjectID, bool)

type Object ¶

type Object struct {
	ID       ObjectID
	Addr     uint64
	Size     uint64
	Children []ObjectID
}

Object is one heap object in the resolved graph.

type ObjectID ¶

type ObjectID uint32

ObjectID identifies one object in a Graph. It is also the object's index in Graph.Objects.

type ObjectRange ¶

type ObjectRange struct {
	Start uint64
	End   uint64
	ID    ObjectID
}

ObjectRange is one half-open address range [Start, End) covered by a single object. Used for interior-pointer resolution. Zero-sized objects are intentionally not registered as ranges.

type Options ¶

type Options struct {
	Strict bool
}

Options tunes the builder. Strict turns warnings into errors.

type RootRef ¶

type RootRef struct {
	ObjectID ObjectID
	Ptr      uint64
	SlotAddr uint64
	Kind     string
	Detail   string
}

RootRef is one resolved pointer from a stack frame, global root, or finalizer record into a heap object.

type Stats ¶

type Stats struct {
	Objects                int
	ObjectBytes            uint64
	Edges                  int
	RawObjectPointers      int
	ZeroObjectPointers     int
	ResolvedObjectPointers int

	UnresolvedPointers       int
	UnresolvedObjectPointers int
	UnresolvedGoroutineRoots int
	UnresolvedGlobalRoots    int
	UnresolvedFinalizerRoots int

	Goroutines            int
	SystemGoroutines      int
	GoroutineRootPointers int
	GlobalRoots           int

	GoroutineReachableObjects int
	GlobalReachableObjects    int
	UnreachableObjects        int

	SharedByGoroutinesObjects int
}

Stats aggregates counters across the analysis.

Pointer accounting (object pointer slots):

RawObjectPointers       = total pointer values seen in object slots,
                          including zero pointers
ZeroObjectPointers      = how many of those were zero (nil)
ResolvedObjectPointers  = non-zero pointers that resolved to a heap
                          object (pre-dedup)
UnresolvedObjectPointers = non-zero pointers that did not resolve
Edges                   = deduplicated child edges in the graph

Invariant:

RawObjectPointers = ZeroObjectPointers + ResolvedObjectPointers + UnresolvedObjectPointers

(Iface/eface data-word edges are decoded at the parser level — see ParseStats.InterfaceFieldsDecoded / EfaceFieldsDecoded — and included in PointerAddrs before the graph builder runs, so they contribute to RawObjectPointers. For current Go runtime versions these counts are always zero because the dump writer only emits fieldKindPtr from GC bitmaps.)

Root accounting tracks unresolved root pointers separately by source category so it is clear whether missing reachability is due to objects, goroutine stacks, globals, or finalizers.