syncutil

Documentation

Overview

Package syncutil provides mutex primitives with optional deadlock detection. Use build tag -tags=deadlock to enable deadlock detection during development.

Index

• Constants
• type Mutex
• type Pauser
  • func NewPauser() *Pauser
  • func (p *Pauser) HasBaselineThrottle() bool
  • func (p *Pauser) IsPaused() bool
  • func (p *Pauser) IsThrottled() bool
  • func (p *Pauser) Level() ThrottleLevel
  • func (p *Pauser) Pause()
  • func (p *Pauser) Resume()
  • func (p *Pauser) SetBaselineThrottle(level ThrottleLevel)
  • func (p *Pauser) SetBaselineThrottleQuanta(work, sleep time.Duration)
  • func (p *Pauser) SetThrottleQuanta(work, sleep time.Duration)
  • func (p *Pauser) Throttle(level ThrottleLevel)
  • func (p *Pauser) Wait(ctx context.Context) error
  • func (p *Pauser) WaitForPacing(ctx context.Context) error
• type RWMutex
• type ThrottleLevel

Constants

const DeadlockEnabled = false

DeadlockEnabled is true if the deadlock detector is enabled.

Types

type Mutex

type Mutex struct {
	sync.Mutex //nolint:forbidigo // this package wraps sync.Mutex
}

A Mutex is a mutual exclusion lock.

type Pauser

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

Pauser is a thread-safe pause/throttle/resume primitive using the closed-channel pattern. When running, Wait returns immediately. When paused, Wait blocks until Resume is called or the context is cancelled. When throttled, Wait enforces a duty cycle: callers run unimpeded for a work quantum, then Wait sleeps for a sleep quantum before the next window.

A nil *Pauser is safe to use: Wait always returns nil.

func NewPauser

func NewPauser() *Pauser

NewPauser returns a Pauser in the running state.

func (*Pauser) HasBaselineThrottle

func (p *Pauser) HasBaselineThrottle() bool

HasBaselineThrottle reports whether running work uses baseline pacing.

func (*Pauser) IsPaused

func (p *Pauser) IsPaused() bool

IsPaused reports whether the Pauser is currently in the paused state. A nil receiver reports false.

func (*Pauser) IsThrottled

func (p *Pauser) IsThrottled() bool

IsThrottled reports whether the Pauser is currently in the throttled state. A nil receiver reports false.

func (*Pauser) Level

func (p *Pauser) Level() ThrottleLevel

Level returns the throttle level applied by the most recent Throttle call. Only meaningful while IsThrottled is true. A nil receiver returns ThrottleLight.

func (*Pauser) Pause

func (p *Pauser) Pause()

Pause requests a full pause. Idempotent: calling Pause when already paused is a no-op. Pause overrides a throttled state.

func (*Pauser) Resume

func (p *Pauser) Resume()

Resume returns to the running state, unblocking all goroutines waiting in Wait. Idempotent: calling Resume when running is a no-op.

func (*Pauser) SetBaselineThrottle

func (p *Pauser) SetBaselineThrottle(level ThrottleLevel)

SetBaselineThrottle enables a duty cycle while the pauser is otherwise in its running state. Explicit Pause and Throttle calls still override it, and Resume returns to this baseline. Baseline pacing does not make IsThrottled true, so status reporting and transaction sizing continue to describe only foreground-media restrictions.

func (*Pauser) SetBaselineThrottleQuanta

func (p *Pauser) SetBaselineThrottleQuanta(work, sleep time.Duration)

SetBaselineThrottleQuanta overrides the running-state baseline duty cycle. Non-positive values are ignored. Intended for configuration and tests.

func (*Pauser) SetThrottleQuanta

func (p *Pauser) SetThrottleQuanta(work, sleep time.Duration)

SetThrottleQuanta overrides the explicit throttle duty cycle. Non-positive values are ignored. Intended for configuration and tests.

func (*Pauser) Throttle

func (p *Pauser) Throttle(level ThrottleLevel)

Throttle requests the duty-cycled throttled state at the given level. Idempotent: calling Throttle with the level already active is a no-op and does not reset the current work window. Calling Throttle with a different level while already throttled switches the duty cycle immediately. Calling Throttle when paused releases blocked waiters into the throttled state.

func (*Pauser) Wait

func (p *Pauser) Wait(ctx context.Context) error

Wait applies the current state to the caller. Running work returns immediately unless a baseline throttle is enabled, paused work blocks until Resume, and explicitly throttled work follows its stronger duty cycle. It returns the context error if the context is cancelled while blocked or sleeping. A nil receiver returns nil.

func (*Pauser) WaitForPacing

func (p *Pauser) WaitForPacing(ctx context.Context) error

WaitForPacing applies baseline and explicit throttle pacing without blocking for a full pause. Use it while a transaction or other resource must be released before the caller can safely honor Pause with Wait.

type RWMutex

type RWMutex struct {
	sync.RWMutex //nolint:forbidigo // this package wraps sync.RWMutex
}

An RWMutex is a reader/writer mutual exclusion lock.

type ThrottleLevel

type ThrottleLevel int

ThrottleLevel selects how aggressively the throttled state's duty cycle slows work down.

const (
	// ThrottleLight is the default while ordinary foreground media is
	// active. 50ms/150ms yields ~25% duty, keeping storage and CPU mostly
	// free for the foreground consumer while still making steady progress.
	ThrottleLight ThrottleLevel = iota
	// ThrottleHeavy is for storage-streaming cores (CD-based, etc.) whose
	// continuous reads are sensitive to any competing I/O. 20ms/300ms
	// yields ~6% duty. On-device testing (MiSTer, CD-streaming arcade
	// core) showed the lighter duty cycle still let indexing's storage
	// bursts interfere with playback, so the work window is short and
	// infrequent enough to stay out of a foreground consumer's way.
	ThrottleHeavy
	// ThrottleBackground is a baseline for long-running jobs even when no
	// media is active. Equal work and sleep quanta reserve regular CPU time
	// for UI, API, reader, and audio work without changing process priority.
	ThrottleBackground
)