cellwatch

type ACState int

type AppActivity struct {
	Name string

	// Procs is how many processes were folded into this name.
	Procs int

	// CPUSeconds is measured CPU time consumed in the window.
	CPUSeconds float64

	// ReadBytes and WriteBytes are measured I/O in the window.
	ReadBytes  uint64
	WriteBytes uint64

	// Share is this application's fraction of attributed system drain, 0 to 1.
	Share float64

	// PctPerHour is the drain rate apportioned to it. ESTIMATE.
	PctPerHour float64

	// Provenance is always ProvEstimated for Share and PctPerHour. It travels
	// with the data so a stored value cannot later be read as a measurement.
	Provenance Provenance `json:"provenance"`
}

type AppTotal struct {
	Name       string  `json:"name"`
	PctPerHour float64 `json:"pct_per_hour_estimate"`
	CPUSeconds float64 `json:"cpu_seconds"`
	ReadBytes  uint64  `json:"read_bytes"`
	WriteBytes uint64  `json:"write_bytes"`
}

type Attribution struct {
	Window time.Duration `json:"window"`

	// Processes is how many processes contributed.
	Processes int `json:"processes"`
	// ProcessesLost is how many were dropped for a counter that moved backwards
	// or an identity that could not be confirmed.
	ProcessesLost int `json:"processes_lost"`

	// CPUCapacityPct is the share of total machine CPU the attributed
	// processes used, and is reported even when the result is Idle, because it
	// is the measurement that explains why the estimate was refused.
	CPUCapacityPct float64 `json:"cpu_capacity_pct"`

	// Idle reports that activity was too low to apportion.
	Idle bool `json:"idle"`

	// Apps is the per-application table, largest share first.
	Apps []AppActivity `json:"apps,omitempty"`

	// Unattributed is the share of drain that no process was credited with.
	Unattributed float64 `json:"unattributed_estimate"`

	// Notes carry the reasons a figure is limited. They are for display.
	Notes []string `json:"notes,omitempty"`

	// Reason explains an empty result.
	Reason string `json:"reason,omitempty"`
}

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

type Capability uint32

type Coverage struct {
	Samples  int       `json:"samples"`
	From     time.Time `json:"from"`
	To       time.Time `json:"to"`
	Expected int       `json:"expected"`
	Pct      float64   `json:"pct"`
}

type Period uint8

type Point struct {
	At         time.Time `json:"at"`
	CPUSeconds float64   `json:"cpu_seconds"`
	ReadBytes  uint64    `json:"read_bytes"`
	WriteBytes uint64    `json:"write_bytes"`
	Share      float64   `json:"share_estimate"`
}

type Provenance uint8

type Range struct {
	From time.Time `json:"from"`
	To   time.Time `json:"to"`
}

type Rate struct {
	// PctPerHour is the smoothed estimate used for display.
	PctPerHour float64

	// RawPctPerHour is the un-smoothed figure computed across the window
	// endpoints. It is reported alongside the smoothed one so a consumer can
	// see how much smoothing was applied, rather than being handed a number
	// with no indication that it is a moving average.
	RawPctPerHour float64

	// Stable reports whether enough history accumulated to trust the figure.
	Stable bool

	// Span is the interval the estimate was computed over.
	Span time.Duration

	// Samples is how many readings contributed.
	Samples int

	// Reason explains a non-Stable result in a form fit for display, so a UI
	// can say why it is waiting rather than showing a wrong number.
	Reason string
}

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

type RateParams struct {
	// MinSpan is the shortest interval over which a rate is considered
	// measured. Below this the result is a quantiser reading.
	MinSpan time.Duration

	// MinSamples is the smallest number of readings that can produce a rate.
	MinSamples int

	// Alpha is the weight given to a new observation in the exponential
	// moving average applied to the displayed figure. Lower is smoother.
	Alpha float64
}

type Reader interface {
	// Read returns the current state. A machine with no battery returns a
	// Status with Present false and a nil error: that is an answer, not a
	// failure. A read that genuinely could not be performed returns an error.
	Read() (Status, error)
}

type Sample struct {
	At     time.Time
	Pct    float64
	AC     ACState
	Charge bool
}

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

type SamplerConfig struct {
	// Reader supplies battery state. Required.
	Reader Reader
	// Store receives readings. Required.
	Store Store
	// Interval is the sampling period. Values below 5s are raised to it.
	//
	// The floor is not a politeness setting. The charge counter is quantised to
	// whole percentage points, so sampling faster than the quantisation does
	// not resolve anything; it multiplies the work and the storage by the
	// sampling rate while producing identical numbers.
	Interval time.Duration
	// Attrib enables per-application attribution, which enumerates every
	// process on the machine and is therefore markedly more expensive.
	Attrib bool
	// Out, when set, receives a line per pass.
	Out io.Writer
}

type SamplerStats struct {
	Started  time.Duration `json:"started_for"`
	Samples  int           `json:"samples"`
	Recorded int           `json:"recorded"`
	Skipped  int           `json:"skipped"`
	LastErr  string        `json:"last_error,omitempty"`
}

type Series struct {
	App    string  `json:"app"`
	Tier   Tier    `json:"tier"`
	Points []Point `json:"points"`
}

type Status struct {
	// Present is false when the platform reported no battery, which is the
	// normal answer for a desktop rather than a failure.
	Present bool

	// Count is the number of batteries the platform reported. Windows
	// GetSystemPowerStatus reports only the first pack, so a two-battery
	// machine reads 1.
	Count int

	// Source names the mechanism that produced this reading, for example
	// "GetSystemPowerStatus". It is a diagnostic for humans and logs, not a
	// stable API; callers should not switch on it.
	Source string

	// AC is the mains-line state.
	AC ACState

	// Status is the platform's own status word verbatim: "Charging",
	// "Discharging", "Full", "Not charging" or "Unknown". Empty when the
	// platform has no such word.
	Status string

	// Charging is taken from the platform's own charging flag. It is never
	// inferred from the sign of a current reading, because that sign
	// convention is not consistent across platforms.
	Charging bool

	// Full is true when the platform reports the pack fully charged.
	Full bool

	// ChargePct is charge remaining, 0 to 100.
	ChargePct   float64
	ChargeKnown bool

	// Watts is instantaneous power draw for the whole machine. Consult
	// Wattage to judge how much it is worth.
	Watts      float64
	WattsKnown bool
	Wattage    WattageSource

	// FullWh is present full-charge capacity in watt-hours.
	FullWh      float64
	FullWhKnown bool

	// DesignWh is factory design capacity in watt-hours.
	DesignWh      float64
	DesignWhKnown bool

	// HealthPct is FullWh as a percentage of DesignWh.
	HealthPct   float64
	HealthKnown bool

	// Cycles is the completed charge-cycle count. Absent on most platforms.
	Cycles      int
	CyclesKnown bool

	// TimeToEmptyS is the platform's own time-remaining estimate in seconds.
	// Firmware reports an unsigned sentinel rather than a negative number when
	// the value is meaningless, so readers must reject anything at or above
	// 1<<31 before trusting it.
	TimeToEmptyS     int64
	TimeToEmptyKnown bool

	// TemperatureC is pack temperature where the platform exposes it. It is
	// cosmetic and is not used in any calculation.
	TemperatureC     float64
	TemperatureKnown bool

	// Cap is the set of fields this platform actually reported.
	Cap Capability
}

type Store interface {
	// Record writes one reading and folds it into the rollup tiers.
	Record(ctx context.Context, s Status) error

	// Apps records per-application activity for a window. Attribution is an
	// estimate derived from CPU and I/O weight, never a measurement, and every
	// stored value carries that provenance.
	Apps(ctx context.Context, at time.Time, apps []AppActivity) error

	// TopApps returns the highest attributed applications within a range.
	TopApps(ctx context.Context, r Range, n int) ([]AppTotal, error)

	// Usage summarises system activity and coverage over a range.
	Usage(ctx context.Context, r Range) (*UsageReport, error)

	// AppHistory returns one application's attributed activity over a range.
	AppHistory(ctx context.Context, app string, r Range) (Series, error)

	// Close releases the database.
	Close() error
}

type SystemUsage struct {
	ChargeStartPct     float64 `json:"charge_start_pct"`
	ChargeEndPct       float64 `json:"charge_end_pct"`
	ChargeLostPct      float64 `json:"charge_lost_pct"`
	DrainPctPerHour    float64 `json:"drain_pct_per_hour_estimate"`
	ChargingSamples    int     `json:"charging_samples"`
	DischargingSamples int     `json:"discharging_samples"`
}

type Tier uint8

type UsageReport struct {
	Range      Range       `json:"range"`
	System     SystemUsage `json:"system"`
	Coverage   Coverage    `json:"coverage"`
	Provenance Provenance  `json:"provenance"`
	Apps       []AppTotal  `json:"apps,omitempty"`
	Notes      []string    `json:"notes,omitempty"`
}

type WattageSource uint8