syncutil

Documentation

Index

• type Mutex
• type RWMutex
• type TimedMutex
  • func MakeTimedMutex(cb TimingFn) TimedMutex
  • func (tm *TimedMutex) AssertHeld()
  • func (tm *TimedMutex) Lock()
  • func (tm *TimedMutex) Unlock()
• type TimingFn
  • func ThresholdLogger(ctx context.Context, warnDuration time.Duration, ...) TimingFn

Types

type Mutex

type Mutex struct {
	sync.Mutex
}

A Mutex is a mutual exclusion lock.

type RWMutex

type RWMutex struct {
	sync.RWMutex
}

An RWMutex is a reader/writer mutual exclusion lock.

type TimedMutex

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

TimedMutex is a mutex which dumps a stack trace via the supplied callback whenever a lock is unlocked after having been held for longer than the supplied duration, which must be strictly positive.

func MakeTimedMutex

func MakeTimedMutex(cb TimingFn) TimedMutex

MakeTimedMutex creates a TimedMutex which warns when an Unlock happens more than warnDuration after the corresponding lock. It will use the supplied context and logging callback for the warning message; a nil logger falls back to Fprintf to os.Stderr.

func (*TimedMutex) AssertHeld

func (tm *TimedMutex) AssertHeld()

AssertHeld may panic if the mutex is not locked (but it is not required to do so). Functions which require that their callers hold a particular lock may use this to enforce this requirement more directly than relying on the race detector.

Note that we do not require the lock to be held by any particular thread, just that some thread holds the lock. This is both more efficient and allows for rare cases where a mutex is locked in one thread and used in another.

TODO(bdarnell): Add an equivalent method to syncutil.Mutex (possibly a no-op depending on a build tag)

func (*TimedMutex) Lock

func (tm *TimedMutex) Lock()

Lock implements sync.Locker.

func (*TimedMutex) Unlock

func (tm *TimedMutex) Unlock()

Unlock implements sync.Locker.

type TimingFn

type TimingFn func(heldFor time.Duration)

TimingFn is a callback passed to MakeTimedMutex. It is invoked with the measured duration of the critical section of the associated mutex after each Unlock operation.

func ThresholdLogger

func ThresholdLogger(
	ctx context.Context,
	warnDuration time.Duration,
	printf func(context.Context, string, ...interface{}),
	record TimingFn,
) TimingFn

ThresholdLogger returns a timing function which calls 'record' for each measured duration and, for measurements exceeding 'warnDuration', invokes 'printf' with the passed context and a detailed stack trace.