imzrt

package
v0.0.18 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 28, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func WindowDelta

func WindowDelta(cur, prev goruntime.Histogram, out *WindowedHistogram)

WindowDelta writes cur-prev into out, reusing out's slice backings. The runtime histograms are cumulative since process start and share fixed boundaries, so the per-interval distribution is the bucket-wise difference (ADR-0061 Q1/O1). A length mismatch — the empty first tick, before any prior snapshot exists — yields all-zero counts rather than mistaking the whole cumulative history for a single interval. A bucket whose count went backwards (a counter reset, not expected in practice) clamps to zero.

Types

type App

type App struct {
	// contains filtered or unexported fields
}

App is the per-window imzrt instance. The registry's factory ctor allocates a fresh App per Open(); all instances read the one shared Sampler. M1 carries only chrome state (the WidgetIdStack and the spacing density); user-visible per-window selections land here as later milestones add panels with controls.

func (*App) Frame

func (inst *App) Frame(ctx app.FrameContextI) (err error)

Frame renders one frame of the imzrt window body. The host has already pre-pushed a window-unique salt onto inst.ids, so widget ids derived from it are scoped per window.

func (*App) Manifest

func (inst *App) Manifest() (m app.Manifest)

func (*App) Mount

func (inst *App) Mount(ctx app.MountContextI) (err error)

func (*App) Unmount

func (inst *App) Unmount(ctx app.MountContextI) (err error)

type PublishedSnapshot

type PublishedSnapshot struct {
	SampledAtUnixMs int64

	// Shared time axis (unix seconds).
	HistTimeUnixSec []float64

	// Heap sawtooth + stacked memory-class bands (MiB).
	HistHeapObjectsMiB []float64 // also the sawtooth "heap in use" line + bottom band
	HistHeapGoalMiB    []float64 // GC trigger target
	HistIdleMiB        []float64 // heap free + unused + released
	HistStacksMiB      []float64 // heap stacks + OS thread stacks
	HistMetadataMiB    []float64 // runtime metadata
	HistOtherMiB       []float64 // other + profiling buckets
	HistTotalMiB       []float64 // total mapped (≈ sum of bands)
	HistGoroutines     []float64

	// Latest scalars for instant readouts and the top bar.
	Goroutines       uint64
	GomaxProcs       uint64
	HeapObjectsBytes uint64
	HeapLiveBytes    uint64
	HeapGoalBytes    uint64
	IdleBytes        uint64
	StacksBytes      uint64
	MetadataBytes    uint64
	OtherBytes       uint64
	TotalMappedBytes uint64
	ReleasedBytes    uint64
	HeapObjectsCount uint64
	GCCyclesTotal    uint64
	GCCyclesForced   uint64
	GOGCPercent      uint64
	GOMemLimitBytes  uint64 // goruntime.MemLimitUnset when GOMEMLIMIT is not set

	// Derived current rates.
	AllocRateBytesPerSec float64
	GCPerSec             float64

	// GC dynamics (M2): rolling history plus current-interval scalars.
	HistPauseP50Ms     []float64 // rolling per-interval p50 GC pause (ms)
	HistPauseP99Ms     []float64 // rolling per-interval p99 GC pause (ms)
	HistPauseMaxMs     []float64 // rolling per-interval max GC pause (ms)
	HistGCPerSec       []float64 // total GC cycles/s
	HistGCForcedPerSec []float64 // forced GC cycles/s
	HistAllocMiBs      []float64 // allocation rate (MiB/s)
	PauseP50Sec        float64
	PauseP99Sec        float64
	PauseMaxSec        float64
	PausesInWindow     uint64
	GCForcedPerSec     float64
	AllocObjPerSec     float64

	// Scheduler dynamics (M3).
	HistSchedP99Ms []float64 // rolling per-interval p99 scheduling latency (ms)
	SchedP99Sec    float64
	// Spectrogram: the current interval's per-bucket /sched/latencies counts plus
	// the bucket boundaries. The panel pushes one column per tick.
	SchedLatColCounts  []uint64
	SchedLatColBuckets []float64
	// STW pause counts this interval (gc / other). STWAvailable is false on a Go
	// version lacking /sched/pauses/total/* — the panel hides the row.
	STWGCCount    uint64
	STWOtherCount uint64
	STWAvailable  bool

	// Count of curated runtime metrics absent on this Go version (0 on a current toolchain).
	MissingMetrics int
}

PublishedSnapshot is the read-only frame the renderer consumes. Built once per Sampler tick and replaced atomically; slices are owned by the snapshot and never mutated after publication, so a concurrent reader sees a coherent view.

Memory series are stored in MiB. The five class bands (objects / idle / stacks / metadata / other) partition the mapped total and stack to it; the panel computes their running cumulative for the stacked-area draw.

func (*PublishedSnapshot) MemLimitSet

func (inst *PublishedSnapshot) MemLimitSet() (set bool)

MemLimitSet reports whether GOMEMLIMIT is configured (not the unset sentinel).

type Sampler

type Sampler struct {
	// contains filtered or unexported fields
}

Sampler runs a goroutine that periodically reads the Go runtime via a goruntime.Collector and publishes a PublishedSnapshot through atomic.Pointer. It is a process-wide singleton (ensureSampler): there is exactly one Go runtime per process, so one shared history is the correct model, and it keeps recording while every window is hidden.

func NewSampler

func NewSampler(opts SamplerOptions) (inst *Sampler, err error)

NewSampler builds a Sampler. The error return mirrors imztop's sampler surface and leaves room for future construction-time validation; it is nil today.

func (*Sampler) Close

func (inst *Sampler) Close() (err error)

func (*Sampler) Interval

func (inst *Sampler) Interval() (d time.Duration)

func (*Sampler) IntervalLabel

func (inst *Sampler) IntervalLabel() (out string)

IntervalLabel returns the configured tick interval as a short label for the top-bar status row.

func (*Sampler) IsPaused

func (inst *Sampler) IsPaused() (p bool)

func (*Sampler) Latest

func (inst *Sampler) Latest() (snap *PublishedSnapshot)

func (*Sampler) Pause

func (inst *Sampler) Pause(p bool)

func (*Sampler) SetInterval

func (inst *Sampler) SetInterval(d time.Duration)

SetInterval changes the tick period, clamped to [100ms, 60s]. The next tick after the current ticker fires adopts the new period.

func (*Sampler) Start

func (inst *Sampler) Start(ctx context.Context)

type SamplerI

type SamplerI interface {
	Start(ctx context.Context)
	Latest() (snap *PublishedSnapshot)
	Pause(p bool)
	IsPaused() (p bool)
	Close() (err error)
}

SamplerI is the public surface a Sampler implements.

type SamplerOptions

type SamplerOptions struct {
	UpdateInterval time.Duration
	HistoryWindow  time.Duration
}

SamplerOptions configures a Sampler.

type SlidingWindow

type SlidingWindow[T any] = slidingwindow.Window[T]

SlidingWindow aliases the shared observability sliding-window buffer. It was formerly a verbatim copy of imztop's type; ADR-0061 SD13 (open question 3) tracked lifting it into a shared package, done here. See slidingwindow.Window for semantics (memmove-on-full, stable backing, per-tick copy-out; not safe for concurrent use).

func NewSlidingWindow

func NewSlidingWindow[T any](capacity int32) *SlidingWindow[T]

NewSlidingWindow constructs a SlidingWindow holding at most capacity values (clamped to a minimum of 1).

type WindowedHistogram

type WindowedHistogram struct {
	Buckets []float64
	Counts  []uint64
}

WindowedHistogram is a per-interval histogram: the bucket-wise difference of two cumulative goruntime.Histogram snapshots. Buckets are the runtime's own boundaries (len = len(Counts)+1); Counts[i] is the number of observations that fell in [Buckets[i], Buckets[i+1]) during the interval.

func (*WindowedHistogram) Max

func (inst *WindowedHistogram) Max() (v float64)

Max returns the finite upper edge of the highest non-empty bucket — the ceiling of the observed values — or 0 if the window is empty. An open top bucket (+Inf edge) falls back to its lower edge.

func (*WindowedHistogram) Quantile

func (inst *WindowedHistogram) Quantile(q float64) (v float64)

Quantile returns the value at q in [0,1], interpolated within the bucket it falls in. Returns 0 for an empty window. The runtime's bucket boundaries are exponentially spaced, so within-bucket interpolation is an approximation ("to the nearest bucket edge"). The open first/last buckets (±Inf edges) clamp to their finite neighbour, so the result is always finite.

func (*WindowedHistogram) Total

func (inst *WindowedHistogram) Total() (n uint64)

Total returns the number of observations in the window.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL