sync

README

sync with Context

This is a small Golang library that tries to mimic (unless otherwise stated in doc) the behaviour of

• sync.Mutex
• sync.Cond

but adds context.Context to support deadlines.

So far very little time has been spent on performance here, but here are some crude benchmarks:

goos: darwin
goarch: amd64
pkg: github.com/JensRantil/sync-with-context
BenchmarkMutexLockUnlock-8              	25858257	        43.2 ns/op
BenchmarkStandardMutexLockUnlock-8      	122055702	         9.81 ns/op
BenchmarkMutexLockWithContextUnlock-8   	26493699	        43.7 ns/op
PASS
ok  	github.com/JensRantil/sync-with-context	4.665s

That is the sync.Mutex in standard library is about 77% faster than this mutex.

Documentation

Index

• type Cond
  • func NewCond(l sync.Locker) *Cond
  • func (c *Cond) Broadcast()
  • func (c *Cond) Signal()
  • func (c *Cond) Wait()
  • func (c *Cond) WaitWithContext(ctx context.Context) error
• type Mutex
  • func (m *Mutex) Lock()
  • func (m *Mutex) LockWithContext(ctx context.Context) error
  • func (m *Mutex) Unlock()

Types

type Cond

type Cond struct {
	L sync.Locker
	// contains filtered or unexported fields
}

Cond behaves similarly to sync.Cond, but also supports context.Context. It has slight nuance in behaviour for Broadcast and Signal methods.

func NewCond

func NewCond(l sync.Locker) *Cond

NewCond returns a WaitCond.

func (*Cond) Broadcast

func (c *Cond) Broadcast()

Broadcast wakes all goroutines waiting on c.

Compared to sync.Cond.Broadcast, a lock _must_ be held when calling this.

func (*Cond) Signal

func (c *Cond) Signal()

Signal wakes one goroutine waiting on c, if there is any.

Compared to sync.Cond.Signal, a lock _must_ be held when calling this.

func (*Cond) Wait

func (c *Cond) Wait()

Wait atomically unlocks c.L and suspends execution of the calling goroutine. After later resuming execution, Wait locks c.L before returning. Unlike in other systems, Wait cannot return unless awoken by Broadcast or Signal.

Because c.L is not locked when Wait first resumes, the caller typically cannot assume that the condition is true when Wait returns. Instead, the caller should Wait in a loop:

c.L.Lock()
for !condition() {
    c.Wait()
}
... make use of condition ...
c.L.Unlock()

func (*Cond) WaitWithContext

func (c *Cond) WaitWithContext(ctx context.Context) error

WaitWithContext behaves similar as Wait, but also supports deadline. It returns context.Err().

type Mutex

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

A Mutex is a mutual exclusion lock. The zero value for a Mutex is an unlocked mutex.

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) LockWithContext

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

LockWithContext locks m. It behaves similarly to calling m.Lock() but also adds support for context.Context deadlines.

The function returns ctx.Err() if the context deadlined, nil otherwise. The caller _must_ check the error code to decide if it should unlock the mutex later or not.

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.