fifomu

Documentation

Overview

Package fifomu provides a Mutex whose Lock method returns the lock to callers in FIFO call order. This is in contrast to sync.Mutex, where a single goroutine can repeatedly lock and unlock and relock the mutex without handing off to other lock waiter goroutines (that is, until after a 1ms starvation threshold, at which point sync.Mutex enters a FIFO "starvation mode" for those starved waiters, but that's too late for some use cases).

fifomu.Mutex implements the exported methods of sync.Mutex and thus is a drop-in replacement (and by extension also implements sync.Locker). It also provides a bonus context-aware Mutex.LockContext method.

Note: unless you need the FIFO behavior, you should prefer sync.Mutex. For typical workloads, its "greedy-relock" behavior requires less goroutine switching and yields better performance.

Index

• type Mutex
  • func (m *Mutex) Lock()
  • func (m *Mutex) LockContext(ctx context.Context) error
  • func (m *Mutex) TryLock() bool
  • func (m *Mutex) Unlock()

Types

type Mutex

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

Mutex is a mutual exclusion lock whose Lock method returns the lock to callers in FIFO call order.

A Mutex must not be copied after first use.

The zero value for a Mutex is an unlocked mutex.

Mutex implements the same methodset as sync.Mutex, so it can be used as a drop-in replacement. It implements an additional method Mutex.LockContext, which provides context-aware locking.

func (*Mutex) Lock

func (m *Mutex) Lock()

Lock locks m.

If the lock is already in use, the calling goroutine blocks until the mutex is available.

func (*Mutex) LockContext

func (m *Mutex) LockContext(ctx context.Context) error

LockContext locks m.

If the lock is already in use, the calling goroutine blocks until the mutex is available or ctx is done.

On failure, LockContext returns context.Cause(ctx) and leaves the mutex unchanged.

If ctx is already done, LockContext may still succeed without blocking.

func (*Mutex) TryLock

func (m *Mutex) TryLock() bool

TryLock tries to lock m and reports whether it succeeded.

func (*Mutex) Unlock

func (m *Mutex) Unlock()

Unlock unlocks m. It is a run-time error if m is not locked on entry to Unlock.

A locked Mutex is not associated with a particular goroutine. It is allowed for one goroutine to lock a Mutex and then arrange for another goroutine to unlock it.