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 (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) SetThrottleQuanta(work, sleep time.Duration)
- func (p *Pauser) Throttle(level ThrottleLevel)
- func (p *Pauser) Wait(ctx context.Context) error
- type RWMutex
- type ThrottleLevel
Constants ¶
const DeadlockEnabled = false
DeadlockEnabled is true if the deadlock detector is enabled.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Pauser ¶ added in v2.11.0
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 ¶ added in v2.11.0
func NewPauser() *Pauser
NewPauser returns a Pauser in the running state.
func (*Pauser) IsPaused ¶ added in v2.11.0
IsPaused reports whether the Pauser is currently in the paused state. A nil receiver reports false.
func (*Pauser) IsThrottled ¶ added in v2.16.0
IsThrottled reports whether the Pauser is currently in the throttled state. A nil receiver reports false.
func (*Pauser) Level ¶ added in v2.16.0
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 ¶ added in v2.11.0
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 ¶ added in v2.11.0
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) SetThrottleQuanta ¶ added in v2.16.0
SetThrottleQuanta overrides the throttle duty cycle. Non-positive values are ignored. Intended for configuration and tests.
func (*Pauser) Throttle ¶ added in v2.16.0
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 ¶ added in v2.11.0
Wait applies the current state to the caller. It returns nil immediately when running, blocks until Resume while paused, and enforces the duty cycle while throttled. It returns the context error if the context is cancelled while blocked or sleeping. A nil receiver returns nil.
type ThrottleLevel ¶ added in v2.16.0
type ThrottleLevel int
ThrottleLevel selects how aggressively the throttled state's duty cycle slows work down.
const ( // ThrottleLight is the default for most cores: work for one quantum, // then sleep. 50ms/150ms yields ~25% duty, keeping storage and CPU // mostly free for a 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 )
Source Files