sync
Mutexes, condition variables, wait groups, read-write locks, semaphores and once, for coordinating threads.
import sync
When several threads change the same variable they have to take turns, or the result depends on the order the threads happen to run in. The sync package has the classic tools for taking turns, built on the operating system's threads library:
- A mutex: each thread takes the lock before touching the data and releases it afterwards. An RWMutex lets many readers in at once.
- A condition variable: a thread sleeps until another one says that something has changed.
- A wait group: call
Addbefore starting a piece of work,Doneat its end, andWaituntil the count is back to zero. - A semaphore caps how many threads are inside a part at once, and a once runs setup a single time.
Threads themselves come from spawn and the thread package. For a single shared number, atomic is cheaper than a lock; to hand values from one thread to another, chan does the locking and waiting for you; to cancel work, ctx.
The things people get wrong:
- Using a value that was never created. Every tool here is made with a
New...function; a zerosync.Mutex {}has no lock inside and crashes onLock. Globals are declared with{}and created at the top ofmain. - Locking twice. A mutex is not reentrant: a thread that calls
Lockon a mutex it already holds waits forever.Doholds a lock while its function runs, so callingDoon the sameOncefrom inside it hangs too. - Waiting on a condition without a loop.
WaitCondcan return before the condition is true; always wait insideuntil not condition:. - Forgetting
Destroy.... Each tool holds operating system memory; destroy it after the last thread that uses it has been joined.
Keep data consistent with a mutex
A lock is not only for counters. Anything that has to stay true across several variables, such as "the money in all accounts adds up to the same total", needs every change to happen while the lock is held. Take the lock at the top of the function and put Unlock in a defer, so it is released on every return path, including the early ret.
import sync
mut accounts := Vector {} as Vector<int>
mut lock := sync.Mutex {}
mut group := sync.WaitGroup {}
func transfer(from: int, dest: int, amount: int): bool:
sync.Lock(lock)
defer sync.Unlock(lock)
if accounts.Get(from) < amount:
ret false
end
accounts.Set(from, accounts.Get(from) - amount)
accounts.Set(dest, accounts.Get(dest) + amount)
ret true
end
func clerk():
repeat 1000 in i:
transfer(i % 3, (i + 1) % 3, 7)
end
sync.Done(group)
end
func main:
lock = sync.NewMutex()
group = sync.NewWaitGroup()
accounts.Push(500)
accounts.Push(300)
accounts.Push(200)
sync.Add(group, 4)
mut workers := Vector {} as Vector<i64>
defer workers.Free()
repeat 4:
workers.Push(spawn(clerk))
end
sync.Wait(group)
each t in workers:
join(t)
end
total := accounts.Get(0) + accounts.Get(1) + accounts.Get(2)
println "money in the bank:", total
println "a transfer that is too big:", transfer(0, 1, 100000)
accounts.Free()
sync.DestroyWaitGroup(group)
sync.Destroy(lock)
endFour threads move money around 4000 times and the total is still 1000. Without the lock two threads could read the same balance at once and one of the changes would be lost.
Many readers, few writers
When data is read far more often than it is changed, such as settings or a cache, a plain mutex makes readers wait for each other for no reason. An RWMutex lets any number of readers in together with RLock, and gives a writer the data to itself with WLock.
import sync
mut settings := HashMap {} as HashMap<str, int>
mut guard := sync.RWMutex {}
mut reads := 0
mut count lock := sync.Mutex {}
func reader():
repeat 200:
sync.RLock(guard)
limit := settings.Get("limit")
sync.RUnlock(guard)
if limit > 0:
sync.Lock(count lock)
reads++
sync.Unlock(count lock)
end
end
end
func writer():
repeat 1 to 5 in v:
sync.WLock(guard)
settings.Put("limit", v * 10)
sync.WUnlock(guard)
end
end
func main:
guard = sync.NewRWMutex()
count lock = sync.NewMutex()
settings.Put("limit", 5)
a := spawn(reader)
b := spawn(reader)
w := spawn(writer)
join(a)
join(b)
join(w)
println "reads:", reads
println "final limit:", settings.Get("limit")
settings.Free()
sync.Destroy(count lock)
sync.DestroyRWMutex(guard)
endA reader must never write while holding only the read lock. If a reader may need to change the data, take the write lock instead.
Limit how many run at once
A Semaphore holds a number of permits. Acquire takes one and waits when none are left, Release gives it back. With two permits, at most two threads are inside the guarded part at any moment, which is how you cap parallel downloads or database connections.
import sync
mut slots := sync.Semaphore {}
mut lock := sync.Mutex {}
mut running := 0
mut busiest := 0
mut finished := 0
func download():
sync.Acquire(slots)
sync.Lock(lock)
running++
if running > busiest:
busiest = running
end
sync.Unlock(lock)
sync.SleepMs(20)
sync.Lock(lock)
running--
finished++
sync.Unlock(lock)
sync.Release(slots)
end
func main:
slots = sync.NewSemaphore(2)
lock = sync.NewMutex()
mut jobs := Vector {} as Vector<i64>
defer jobs.Free()
repeat 6:
jobs.Push(spawn(download))
end
each t in jobs:
join(t)
end
println "downloads finished:", finished
println "never more than two at once:", busiest <= 2
sync.Destroy(lock)
sync.DestroySemaphore(slots)
endTryAcquire takes a permit only if one is free and returns false at once otherwise, for work that should be skipped rather than queued.
Set something up exactly once
Some setup is expensive and should happen only when it is first needed, but several threads may need it at the same moment. Do runs its function the first time it is called on a Once; every other caller waits until that run has finished and then goes on without running it again.
import sync
mut setup := sync.Once {}
mut table := Vector {} as Vector<int>
mut builds := 0
func build table():
builds++
repeat 10 in i:
table.Push(i * i)
end
end
func square(n: int): int:
sync.Do(setup, (): build table() end)
ret table.Get(n)
end
func worker():
_ := square(3)
end
func main:
setup = sync.NewOnce()
a := spawn(worker)
b := spawn(worker)
c := spawn(worker)
join(a)
join(b)
join(c)
println "square of 7:", square(7)
println "table built", builds, "time"
table.Free()
sync.DestroyOnce(setup)
endA work queue: wait for work, wait for the end
A condition variable is how a thread sleeps until there is something to do instead of checking in a busy loop. The workers below wait on has_work while the queue is empty, and the main thread calls Signal after each push to wake one of them. A wait group counts the jobs: Add before each push, Done when it is processed, and Wait returns when all are done. To stop the workers, set a flag and Broadcast, which wakes all of them.
import sync
mut lock := sync.Mutex {}
mut has_work := sync.CondVar {}
mut jobs_done := sync.WaitGroup {}
mut queue := Vector {} as Vector<int>
mut taken := 0
mut closed := false
mut total := 0
func worker():
sync.Lock(lock)
until true:
until taken == queue.Len() and not closed:
sync.WaitCond(has_work, lock)
end
if taken == queue.Len(): break end
size := queue.Get(taken)
taken++
sync.Unlock(lock)
cost := size * 2
sync.Lock(lock)
total += cost
sync.Done(jobs_done)
end
sync.Unlock(lock)
end
func main:
lock = sync.NewMutex()
has_work = sync.NewCondVar()
jobs_done = sync.NewWaitGroup()
workers := [spawn(worker), spawn(worker), spawn(worker)]
repeat 1 to 10 in size:
sync.Add(jobs_done, 1)
sync.Lock(lock)
queue.Push(size)
sync.Signal(has_work)
sync.Unlock(lock)
end
sync.Wait(jobs_done)
println "all 10 jobs done, total cost", total
sync.Lock(lock)
println "nobody signals, waited 20 ms, woken:", sync.WaitCondTimeout(has_work, lock, 20)
closed = true
sync.Broadcast(has_work)
sync.Unlock(lock)
each t in workers: join(t) end
println "workers stopped"
queue.Free()
sync.DestroyWaitGroup(jobs_done)
sync.DestroyCondVar(has_work)
sync.Destroy(lock)
endWaitCond releases the lock while it sleeps and takes it again before it returns, which is why the worker can check the queue right after it. WaitCondTimeout does the same with a time limit, returning true when it was woken and false when the time ran out. The wait group does not replace join: every spawned thread still has to be joined once.
Pitfalls, and which tool to use
- When two locks are needed, every thread must take them in the same order. Taking A then B in one thread and B then A in another can stop both.
- Keep the locked part short. Do slow work, such as file or network calls, before taking the lock or after releasing it.
- Every
New...has a matchingDestroy.... Call it after the last thread using the value has been joined.
| Situation | Use |
|---|---|
| Several threads change the same data | Mutex |
| Data is read much more often than written | RWMutex |
| Wait until N tasks are done | WaitGroup |
| At most N tasks at a time | Semaphore |
| Setup that must run once | Once |
| Wait until some condition becomes true | CondVar with a Mutex |
| A single shared number | atomic.I64 |
| Hand values from one thread to another | chan.Chan |
Types
Mutex
struct Mutex| Name | Type | Description |
|---|---|---|
handle | void* | The operating system's lock. |
import sync
mut balance := 0
mut lock := sync.Mutex {}
mut group := sync.WaitGroup {}
func deposit():
repeat 500:
sync.Lock(lock)
balance++
sync.Unlock(lock)
end
sync.Done(group)
end
func main:
lock = sync.NewMutex()
group = sync.NewWaitGroup()
sync.Wait(group)
sync.Add(group, 4)
a := spawn(deposit)
b := spawn(deposit)
c := spawn(deposit)
d := spawn(deposit)
sync.Wait(group)
join(a)
join(b)
join(c)
join(d)
println "balance:", balance
sync.DestroyWaitGroup(group)
sync.Destroy(lock)
endCondVar
struct CondVar| Name | Type | Description |
|---|---|---|
handle | void* | The operating system's condition variable. |
import sync
mut ready := false
mut lock := sync.Mutex {}
mut cond := sync.CondVar {}
func producer():
sync.SleepMs(20)
sync.Lock(lock)
ready = true
sync.Broadcast(cond)
sync.Unlock(lock)
end
func main:
lock = sync.NewMutex()
cond = sync.NewCondVar()
start := sync.NowMs()
sync.Lock(lock)
println sync.WaitCondTimeout(cond, lock, 10)
t := spawn(producer)
until not ready:
sync.WaitCond(cond, lock)
end
sync.Unlock(lock)
join(t)
println ready, sync.NowMs() - start >= 20
sync.Signal(cond)
sync.DestroyCondVar(cond)
sync.Destroy(lock)
endWaitGroup
struct WaitGroup| Name | Type | Description |
|---|---|---|
counter | i64* | The number of unfinished pieces of work. |
mu | void* | The internal lock. |
cv | void* | The internal condition variable. |
The example for this item is shown with the ones above: sync-Mutex.salam
RWMutex
struct RWMutex| Name | Type | Description |
|---|---|---|
state | i64* | The internal state: the readers, the writer and the waiting writers. |
mu | void* | The internal lock. |
cv | void* | The internal condition variable. |
import sync
func main:
rw := sync.NewRWMutex()
sync.RLock(rw)
sync.RLock(rw)
println "two readers together"
sync.RUnlock(rw)
sync.RUnlock(rw)
sync.WLock(rw)
println "one writer alone"
sync.WUnlock(rw)
sync.DestroyRWMutex(rw)
sem := sync.NewSemaphore(2)
sync.Acquire(sem)
println sync.TryAcquire(sem), sync.TryAcquire(sem)
sync.Release(sem)
println sync.TryAcquire(sem)
sync.DestroySemaphore(sem)
once := sync.NewOnce()
repeat 3:
sync.Do(once, (): println "only once" end)
end
sync.DestroyOnce(once)
endSemaphore
struct Semaphore| Name | Type | Description |
|---|---|---|
permits | i64* | The number of free permits. |
mu | void* | The internal lock. |
cv | void* | The internal condition variable. |
The example for this item is shown with the ones above: sync-RWMutex.salam
Once
struct Once| Name | Type | Description |
|---|---|---|
done | i64* | Whether the function has run. |
mu | void* | The internal lock. |
The example for this item is shown with the ones above: sync-RWMutex.salam
Functions
NewMutex
func NewMutex(): MutexThe example for this item is shown with the ones above: sync-Mutex.salam
Lock
func Lock(m: Mutex): intThe example for this item is shown with the ones above: sync-Mutex.salam
Unlock
func Unlock(m: Mutex): intThe example for this item is shown with the ones above: sync-Mutex.salam
Destroy
func Destroy(m: Mutex)The example for this item is shown with the ones above: sync-Mutex.salam
SleepMs
func SleepMs(ms: int)The example for this item is shown with the ones above: sync-CondVar.salam
NewCondVar
func NewCondVar(): CondVarThe example for this item is shown with the ones above: sync-CondVar.salam
WaitCond
func WaitCond(cv: CondVar, m: Mutex)The example for this item is shown with the ones above: sync-CondVar.salam
WaitCondTimeout
func WaitCondTimeout(cv: CondVar, m: Mutex, ms: i64): boolWaitCond, but for at most ms milliseconds. Returns true when it was woken and false when the time ran out. The lock is held again either way.The example for this item is shown with the ones above: sync-CondVar.salam
NowMs
func NowMs(): i64The example for this item is shown with the ones above: sync-CondVar.salam
Signal
func Signal(cv: CondVar)The example for this item is shown with the ones above: sync-CondVar.salam
Broadcast
func Broadcast(cv: CondVar)The example for this item is shown with the ones above: sync-CondVar.salam
DestroyCondVar
func DestroyCondVar(cv: CondVar)The example for this item is shown with the ones above: sync-CondVar.salam
NewWaitGroup
func NewWaitGroup(): WaitGroupThe example for this item is shown with the ones above: sync-Mutex.salam
Add
func Add(wg: WaitGroup, delta: i64)delta; call it before starting the work, not inside it.The example for this item is shown with the ones above: sync-Mutex.salam
Done
func Done(wg: WaitGroup)The example for this item is shown with the ones above: sync-Mutex.salam
Wait
func Wait(wg: WaitGroup)The example for this item is shown with the ones above: sync-Mutex.salam
DestroyWaitGroup
func DestroyWaitGroup(wg: WaitGroup)The example for this item is shown with the ones above: sync-Mutex.salam
NewRWMutex
func NewRWMutex(): RWMutexThe example for this item is shown with the ones above: sync-RWMutex.salam
RLock
func RLock(rw: RWMutex)The example for this item is shown with the ones above: sync-RWMutex.salam
RUnlock
func RUnlock(rw: RWMutex)The example for this item is shown with the ones above: sync-RWMutex.salam
WLock
func WLock(rw: RWMutex)The example for this item is shown with the ones above: sync-RWMutex.salam
WUnlock
func WUnlock(rw: RWMutex)The example for this item is shown with the ones above: sync-RWMutex.salam
DestroyRWMutex
func DestroyRWMutex(rw: RWMutex)The example for this item is shown with the ones above: sync-RWMutex.salam
NewSemaphore
func NewSemaphore(permits: i64): SemaphoreThe example for this item is shown with the ones above: sync-RWMutex.salam
Acquire
func Acquire(sem: Semaphore)The example for this item is shown with the ones above: sync-RWMutex.salam
TryAcquire
func TryAcquire(sem: Semaphore): boolThe example for this item is shown with the ones above: sync-RWMutex.salam
Release
func Release(sem: Semaphore)Release adds a permit.The example for this item is shown with the ones above: sync-RWMutex.salam
DestroySemaphore
func DestroySemaphore(sem: Semaphore)The example for this item is shown with the ones above: sync-RWMutex.salam
NewOnce
func NewOnce(): OnceThe example for this item is shown with the ones above: sync-RWMutex.salam
Do
func Do(o: Once, f: func())Do on the same Once.The example for this item is shown with the ones above: sync-RWMutex.salam
DestroyOnce
func DestroyOnce(o: Once)The example for this item is shown with the ones above: sync-RWMutex.salam