waitstable

Documentation

Overview

Package waitstable provides utilities for detecting when a stream or buffer has stabilized (no changes for a configured duration).

Example

Example demonstrates basic usage of the Detector.

config := Config{
	WaitStable: 2 * time.Second,
	Threshold:  500 * time.Millisecond,
}

d := New(config, nil)

// Simulate changes
d.RecordChange()
fmt.Println("Change recorded")

time.Sleep(500 * time.Millisecond)
d.RecordChange()
fmt.Println("Another change recorded")

// Check stability
fmt.Printf("Is stable: %v\n", d.IsStable())
fmt.Println("Time since last change: some duration")

// Wait for stability
time.Sleep(2500 * time.Millisecond)
fmt.Printf("After wait - Is stable: %v\n", d.IsStable())

Output:
Change recorded
Another change recorded
Is stable: false
Time since last change: some duration
After wait - Is stable: true

Index

• func ToleranceDuration(t Tolerance) time.Duration
• func ValidateTolerance(t string) error
• type Config
  • func (c Config) ComputeTimeout() time.Duration
• type Detector
  • func New(config Config, onChangeCb OnChangeFunc) *Detector
  • func (d *Detector) CheckAndReport() (timeSinceLastChange time.Duration, stable bool)
  • func (d *Detector) Config() Config
  • func (d *Detector) IsStable() bool
  • func (d *Detector) MaxWaitReached() bool
  • func (d *Detector) RecordChange()
  • func (d *Detector) Reset()
  • func (d *Detector) SetOnChange(cb OnChangeFunc)
  • func (d *Detector) TimeSinceCreation() time.Duration
  • func (d *Detector) TimeSinceLastChange() time.Duration
  • func (d *Detector) TimeUntilMaxWait() time.Duration
• type FlagOptions
  • func (o FlagOptions) ComputeConfig() Config
  • func (o FlagOptions) IsEnabled() bool
• type OnChangeFunc
• type Tolerance

Examples

• Package
• Detector.IsStable
• New

Functions

func ToleranceDuration

func ToleranceDuration(t Tolerance) time.Duration

ToleranceDuration returns the stability timeout for a given tolerance level.

func ValidateTolerance

func ValidateTolerance(t string) error

ValidateTolerance checks if a tolerance string is valid.

Types

type Config

type Config struct {
	// WaitStable is the base duration for stability detection.
	// Combined with Tolerance to determine the actual timeout.
	WaitStable time.Duration

	// Tolerance determines how long to wait before considering stable.
	// Values: low (500ms), normal (2s), high (5s)
	Tolerance Tolerance

	// MaxWait is the maximum time to wait for stability.
	// If set and exceeded, stability is forced regardless of activity.
	// Set to 0 for no maximum.
	MaxWait time.Duration

	// Threshold is the frequency at which to check for changes.
	// This determines the granularity of change detection.
	Threshold time.Duration
}

Config holds configuration for stability detection.

func (Config) ComputeTimeout

func (c Config) ComputeTimeout() time.Duration

ComputeTimeout calculates the actual timeout duration based on WaitStable and Tolerance.

type Detector

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

Detector tracks whether a stream has stabilized by monitoring changes. It is safe for concurrent use.

func New

func New(config Config, onChangeCb OnChangeFunc) *Detector

New creates a new Detector with the given configuration. If onChangeCb is nil, no callback will be invoked on changes.

Example

ExampleNew demonstrates using a change callback.

changeCount := 0

onChange := func(timeSinceLastChange time.Duration) {
	changeCount++
	fmt.Printf("Change #%d detected\n", changeCount)
}

config := Config{
	WaitStable: 1 * time.Second,
	Threshold:  100 * time.Millisecond,
}

d := New(config, onChange)

// Record changes
d.RecordChange()
time.Sleep(200 * time.Millisecond)
d.RecordChange()

fmt.Printf("Total changes recorded: %d\n", changeCount)

Output:
Change #1 detected
Change #2 detected
Total changes recorded: 2

func (*Detector) CheckAndReport

func (d *Detector) CheckAndReport() (timeSinceLastChange time.Duration, stable bool)

CheckAndReport checks if the stream is stable and invokes the callback if enabled. Returns the time since last change and whether stability has been achieved.

func (*Detector) Config

func (d *Detector) Config() Config

Config returns the detector's current configuration.

func (*Detector) IsStable

func (d *Detector) IsStable() bool

IsStable returns true if: 1. Stream has no changes for the configured timeout duration, OR 2. MaxWait duration has been exceeded Returns false if stability detection is disabled (WaitStable == 0 and Tolerance == "").

Example

ExampleDetector_IsStable demonstrates monitoring a stream for stability.

config := Config{
	WaitStable: 1500 * time.Millisecond,
	Threshold:  500 * time.Millisecond,
}

d := New(config, nil)

// Simulate stream activity
fmt.Println("Monitoring stream...")

for i := 0; i < 5; i++ {
	time.Sleep(300 * time.Millisecond)
	d.RecordChange()
	fmt.Printf("Event %d - Stable: %v\n", i+1, d.IsStable())
}

// Wait for final stability
fmt.Println("Waiting for stability...")
for !d.IsStable() {
	time.Sleep(100 * time.Millisecond)
}
fmt.Println("Stream stable!")

Output:
Monitoring stream...
Event 1 - Stable: false
Event 2 - Stable: false
Event 3 - Stable: false
Event 4 - Stable: false
Event 5 - Stable: false
Waiting for stability...
Stream stable!

func (*Detector) MaxWaitReached

func (d *Detector) MaxWaitReached() bool

MaxWaitReached returns true if the MaxWait timeout has been exceeded. Returns false if MaxWait is not configured (0).

func (*Detector) RecordChange

func (d *Detector) RecordChange()

RecordChange marks that a change has occurred and invokes the OnChange callback. This resets the stability timer.

func (*Detector) Reset

func (d *Detector) Reset()

Reset resets the stability timer to now. Use this to signal the start of monitoring or to manually reset the detector state.

func (*Detector) SetOnChange

func (d *Detector) SetOnChange(cb OnChangeFunc)

SetOnChange updates the OnChange callback.

func (*Detector) TimeSinceCreation

func (d *Detector) TimeSinceCreation() time.Duration

TimeSinceCreation returns the total time elapsed since the detector was created.

func (*Detector) TimeSinceLastChange

func (d *Detector) TimeSinceLastChange() time.Duration

TimeSinceLastChange returns the duration since the last recorded change.

func (*Detector) TimeUntilMaxWait

func (d *Detector) TimeUntilMaxWait() time.Duration

TimeUntilMaxWait returns the time remaining until MaxWait is exceeded. Returns 0 if MaxWait is not set or has already been exceeded.

type FlagOptions

type FlagOptions struct {
	// Enabled indicates if stability monitoring is enabled
	Enabled bool
	// Tolerance is the stability tolerance level (low/normal/high)
	Tolerance string
	// MaxWait is the maximum total time to wait
	MaxWait time.Duration
	// Threshold is the check frequency
	Threshold time.Duration
}

FlagOptions groups flag values commonly used when adding stability flags to commands

func (FlagOptions) ComputeConfig

func (o FlagOptions) ComputeConfig() Config

ComputeConfig creates a Config from FlagOptions, computing the appropriate timeout. When enabled is true, it uses the tolerance level to determine the wait duration. Returns a config with WaitStable=0 if not enabled (which makes IsStable() return false).

func (FlagOptions) IsEnabled

func (o FlagOptions) IsEnabled() bool

IsEnabled returns true if stability monitoring should be active

type OnChangeFunc

type OnChangeFunc func(timeSinceLastChange time.Duration)

OnChangeFunc is called when a change is detected. It receives the time since the last change was detected.

type Tolerance

type Tolerance string

Tolerance defines how long to wait before considering the stream stable.

const (
	// ToleranceLow requires quick stabilization (fast detection)
	ToleranceLow Tolerance = "low"
	// ToleranceNormal is the default, balanced tolerance
	ToleranceNormal Tolerance = "normal"
	// ToleranceHigh allows longer periods of inactivity (slow detection)
	ToleranceHigh Tolerance = "high"
)