chan
A channel for passing values from one thread to another, with a buffer, timeouts and closing.
import chan
A channel is a queue that several threads send values into at one end and receive from at the other; it handles the locks and the waiting for you. You give the value type when you create it, as in chan.Chan<i64>, and call init with a capacity before using it.
When the buffer is full, send waits; when it is empty, recv does. A channel of capacity zero is "unbuffered": the sender waits until a receiver takes the value. After close, sending returns false but receivers still get the values that are left; once the channel is empty, ok turns false and a receiving loop can end.
Use a channel when one thread produces values and another consumes them. For shared data that several threads change in place, sync is the better fit; for a counter, atomic; for running the turns of a loop on every core, pool; and for telling workers to stop, ctx.
The things people get wrong:
- Forgetting
init. A channel declared withchan.Chan {}has no buffer or lock yet and crashes on the firstsend. - Using the value from a failed receive. When
okis false the result is a zero value that means nothing. - Telling a timeout from the end.
recv_timeoutsetsokto false both when the time ran out and when the channel is closed and empty; askis_closedto know which. - Sending a
Vectoror a pointer and then changing it. The channel copies the value, which for those types is only the handle, so both threads see the same memory.
The receive loop
Almost every consumer looks the same: receive in an endless until true: loop and break when ok turns false. That happens only after the channel is closed and empty, so no value is lost. The rule that goes with it: the side that sends is the side that closes, once it has nothing more to send.
import chan
mut orders := chan.Chan {} as chan.Chan<str>
func checkout():
each id in ["A-1001", "A-1002", "A-1003"]:
orders.send(id)
end
orders.Close()
println "after close, send works:", orders.send("A-1004")
end
func main:
orders.init(8)
t := spawn(checkout)
join(t)
println "waiting in the buffer:", orders.Len()
mut ok := true
until true:
id := orders.recv(ok)
if not ok: break end
println "packing", id
end
println "closed and empty:", orders.is_closed(), orders.Len()
orders.Free()
endThe sender filled the buffer and closed the channel before the receiver even started, and still every order came out. A send after close returns false instead of waiting.
A pipeline of stages
Channels connect stages that each do one thing. Here one thread generates numbers, a second squares them, and the main thread adds them up. Each stage closes its output channel when its input runs dry, so the end of the data flows down the pipeline by itself and every loop stops on its own.
import chan
mut numbers := chan.Chan {} as chan.Chan<i64>
mut squares := chan.Chan {} as chan.Chan<i64>
func generate():
repeat 1 to 10 in n:
numbers.send(n as i64)
end
numbers.Close()
end
func square():
mut ok := true
until true:
n := numbers.recv(ok)
if not ok:
break
end
squares.send(n * n)
end
squares.Close()
end
func main:
numbers.init(2)
squares.init(2)
a := spawn(generate)
b := spawn(square)
mut total := 0 as i64
mut count := 0
mut ok := true
until true:
v := squares.recv(ok)
if not ok:
break
end
total += v
count++
end
join(a)
join(b)
println "values through the pipeline:", count
println "sum of squares:", total
numbers.Free()
squares.Free()
endThe channels hold only two values each. When the last stage is slow, the earlier ones wait in send instead of piling up memory, which is called back pressure.
Ask and wait for an answer
Two channels make a request and reply pair: one carries questions to a worker, the other brings the answers back. With capacity zero, each send waits until the other side has taken the value, so the two threads move in step and the answers come back in the order the questions went out.
import chan
mut requests := chan.Chan {} as chan.Chan<str>
mut replies := chan.Chan {} as chan.Chan<str>
func server():
mut ok := true
until true:
name := requests.recv(ok)
if not ok:
break
end
replies.send("hello, " + name)
end
end
func main:
requests.init(0)
replies.init(0)
t := spawn(server)
mut ok := true
each name in ["Sara", "Reza", "Mina"]:
requests.send(name)
println replies.recv(ok)
end
requests.Close()
join(t)
requests.Free()
replies.Free()
endMany senders, one receiver
When several threads send into one channel, none of them can close it, because each one only knows that it is done. Count the senders with a sync.WaitGroup and let one more small thread wait for the group and then close the channel.
import chan
import sync
mut events := chan.Chan {} as chan.Chan<i64>
mut senders := sync.WaitGroup {}
func sensor(base: i64):
repeat 5 in i:
events.send(base + i as i64)
end
sync.Done(senders)
end
func sensor a(): sensor(100) end
func sensor b(): sensor(200) end
func sensor c(): sensor(300) end
func closer():
sync.Wait(senders)
events.Close()
end
func main:
events.init(4)
senders = sync.NewWaitGroup()
sync.Add(senders, 3)
a := spawn(sensor a)
b := spawn(sensor b)
c := spawn(sensor c)
d := spawn(closer)
mut per sensor := [0, 0, 0]
mut ok := true
until true:
v := events.recv(ok)
if not ok:
break
end
per sensor[v / 100 - 1]++
end
join(a)
join(b)
join(c)
join(d)
println "from sensor a:", per sensor[0]
println "from sensor b:", per sensor[1]
println "from sensor c:", per sensor[2]
sync.DestroyWaitGroup(senders)
events.Free()
endValues from different senders arrive interleaved in no fixed order, so the program counts them per sender instead of printing them as they come.
When the channel is full
send waits for room, which is not always what you want. A server under load is often better off refusing extra work at once than making every caller wait. try_send returns false immediately when there is no room, and try_recv does the same for an empty channel.
import chan
func main:
mut queue := chan.Chan {} as chan.Chan<int>
queue.init(3)
mut accepted := 0
mut dropped := 0
repeat 1 to 8 in request:
if queue.try_send(request):
accepted++
else:
dropped++
end
end
println "accepted:", accepted, "dropped:", dropped, "waiting:", queue.Len()
mut ok := true
until true:
r := queue.try_recv(ok)
if not ok:
break
end
println "handling request", r
end
println "queue empty:", queue.Len() == 0
queue.Free()
endBetween the two extremes are send_timeout and recv_timeout, which wait at most the given number of milliseconds.
| If the channel is full or empty | Send | Receive |
|---|---|---|
| Wait as long as it takes | send | recv |
| Wait up to some milliseconds | send_timeout | recv_timeout |
| Do not wait at all | try_send | try_recv |
Two mistakes to avoid: receiving from a channel nobody will ever close or send to waits forever, and calling free while another thread is still using the channel. Join the threads first, then free.
A shorter way to spell it
New builds an initialized channel, so the cast is the only extra spelling: c := chan.New(8) as chan.Chan<i64>. The free functions Send, Recv, TrySend, TryRecv, Close, Len, Capacity and IsClosed take the channel as their first argument and do exactly what the method of the same name does. SendAll sends a whole vector and stops at the first failure; Take receives up to a count; and Drain receives everything that is left until the channel is closed and empty.
import chan
func main:
c := chan.New(3) as chan.Chan<str>
println "capacity:", chan.Capacity(c), "len:", chan.Len(c)
words := Vector {} as Vector<str>
words.Push("one")
words.Push("two")
println "sent:", chan.SendAll(c, words)
println "queued:", chan.Len(c)
words.Free()
mut ok := false
println "first:", chan.Recv(c, ok), ok
println "next:", chan.TryRecv(c, ok), ok
chan.Close(c)
println "closed:", chan.IsClosed(c), "send:", chan.TrySend(c, "late")
left := chan.Drain(c)
println "left:", left.Len()
left.Free()
c.Free()
endSelectRecv is Select with the ok result, and SelectSend waits for the first channel of the vector with room, returning its index, minus one on timeout or minus two when every channel is closed. A zero millisecond limit makes either one a single non-blocking attempt; TrySelect and TrySelectSend are the same thing with the zero already filled in.
Drain and Take wait like recv, so close the channel before draining it and ask for no more values than will arrive. SelectSend only sends to a buffered channel with room: on an unbuffered channel try_send is always false, so give that channel a buffer or use a plain send from a thread.
Types
Chan
struct Chan<T>T.| Name | Type | Description |
|---|---|---|
buf | T* | The buffer of values. |
ctl | i64* | The internal state: the head and tail of the queue, the count and whether it is closed. |
cap | i64 = 0 | The capacity. |
zidx | i64 = 0 | The buffer slot holding the type's zero value, for when nothing was received. |
mu | sync.Mutex | The internal lock. |
not_empty | sync.CondVar | Waking the receivers. |
not_full | sync.CondVar | Waking the senders. |
taken | sync.CondVar | The signal that a value was taken, on an unbuffered channel. |
import chan
import sync
mut jobs := chan.Chan {} as chan.Chan<i64>
mut results := chan.Chan {} as chan.Chan<i64>
mut group := sync.WaitGroup {}
func worker():
mut open := true
until true:
n := jobs.recv(open)
if not open:
break
end
results.send(n * n)
end
sync.Done(group)
end
func main:
jobs.init(4)
results.init(16)
group = sync.NewWaitGroup()
sync.Add(group, 2)
a := spawn(worker)
b := spawn(worker)
repeat 1 to 11 in n:
jobs.send(n)
end
jobs.Close()
sync.Wait(group)
join(a)
join(b)
results.Close()
mut total := 0 as i64
mut open := true
until true:
v := results.recv(open)
if not open:
break
end
total += v
end
println "sum of the squares:", total
println jobs.is_closed(), jobs.Len(), jobs.capacity(), jobs.send(1)
sync.DestroyWaitGroup(group)
jobs.Free()
results.Free()
endInit
func Init(capacity: i64)init
func init(capacity: i64)The example for this item is shown with the ones above: chan-Chan.salam
Send
func Send(v: T): boolsend
func send(v: T): boolThe example for this item is shown with the ones above: chan-Chan.salam
SendTimeout
func SendTimeout(v: T, ms: i64): boolsend_timeout
func send_timeout(v: T, ms: i64): boolsend, but it waits at most ms milliseconds.import chan
func main:
mut c := chan.Chan {} as chan.Chan<str>
c.init(1)
println c.try_send("hello"), c.try_send("again")
println c.send_timeout("late", 20)
mut open := true
println c.try_recv(open), open
_ := c.recv_timeout(open, 20)
println "after 20 milliseconds:", open
println c.send_deadline("a", 0, false)
println c.recv_deadline(open, 20, true), open
c.Free()
endSendDeadline
func SendDeadline(v: T, ms: i64, timed: bool): boolsend_deadline
func send_deadline(v: T, ms: i64, timed: bool): booltimed is true it waits up to ms milliseconds, and otherwise forever.The example for this item is shown with the ones above: chan-Timeout.salam
Recv
func Recv(ok &: bool): Trecv
func recv(ok &: bool): Tok turns false; the returned value then means nothing and must not be used.The example for this item is shown with the ones above: chan-Chan.salam
RecvTimeout
func RecvTimeout(ok &: bool, ms: i64): Trecv_timeout
func recv_timeout(ok &: bool, ms: i64): Trecv, but it waits at most ms milliseconds. If nothing arrives, ok turns false; is_closed tells a timeout from a closed channel.The example for this item is shown with the ones above: chan-Timeout.salam
RecvDeadline
func RecvDeadline(ok &: bool, ms: i64, timed: bool): Trecv_deadline
func recv_deadline(ok &: bool, ms: i64, timed: bool): Ttimed.The example for this item is shown with the ones above: chan-Timeout.salam
TrySend
func TrySend(v: T): booltry_send
func try_send(v: T): boolThe example for this item is shown with the ones above: chan-Timeout.salam
TryRecv
func TryRecv(ok &: bool): Ttry_recv
func try_recv(ok &: bool): Tok; it never waits.The example for this item is shown with the ones above: chan-Timeout.salam
Close
func Close()close
func close()The example for this item is shown with the ones above: chan-Chan.salam
IsClosed
func IsClosed(): boolis_closed
func is_closed(): boolThe example for this item is shown with the ones above: chan-Chan.salam
Len
func Len(): i64len
func len(): i64The example for this item is shown with the ones above: chan-Chan.salam
Capacity
func Capacity(): i64capacity
func capacity(): i64The example for this item is shown with the ones above: chan-Chan.salam
Free
func Free()free
func free()The example for this item is shown with the ones above: chan-Chan.salam
Timer
struct Timerc receives a value when it fires.| Name | Type | Description |
|---|---|---|
c | Chan | The channel that receives a value each time the timer fires. |
cancel | i64* | The flag that tells the timer thread to stop. |
arg | void* | The argument block of the timer thread. |
handle | i64 = 0 | The handle of the timer thread. |
import chan
func main:
mut work := chan.Chan {} as chan.Chan<i64>
work.init(1 as i64)
mut cs := Vector {} as Vector<chan.Chan<i64>>
cs.Push(work)
t := chan.After(30 as i64)
cs.Push(t.c)
mut v := 0 as i64
println "timer fired first: ", chan.Select(cs, v, 2000 as i64)
println "tick value: ", v
chan.StopTimer(t)
k := chan.Tick(10 as i64)
mut ok := false
mut seen := 0
until seen < 3:
k.c.recv(ok)
seen++
end
println "ticks: ", seen
chan.StopTimer(k)
quick := chan.After(500 as i64)
chan.StopTimer(quick)
println "stopped early"
work.Free()
endFunctions
New
func New<T>(capacity: i64): Chan<T>chan.New(4) as chan.Chan<i64>.import chan
func main:
c := chan.New(3) as chan.Chan<str>
println "capacity:", chan.Capacity(c), "len:", chan.Len(c)
words := Vector {} as Vector<str>
words.Push("one")
words.Push("two")
println "sent:", chan.SendAll(c, words)
println "queued:", chan.Len(c)
words.Free()
mut ok := false
println "first:", chan.Recv(c, ok), ok
println "next:", chan.TryRecv(c, ok), ok
chan.Close(c)
println "closed:", chan.IsClosed(c), "send:", chan.TrySend(c, "late")
left := chan.Drain(c)
println "left:", left.Len()
left.Free()
c.Free()
endSend
func Send<T>(c: Chan<T>, v: T): boolsend: sends a value and waits for room, returning false when the channel is closed.The example for this item is shown with the ones above: chan-API.salam
SendTimeout
func SendTimeout<T>(c: Chan<T>, v: T, ms: i64): boolsend_timeout.The example for this item is shown with the ones above: chan-API.salam
TrySend
func TrySend<T>(c: Chan<T>, v: T): booltry_send.The example for this item is shown with the ones above: chan-API.salam
SendAll
func SendAll<T>(c: Chan<T>, values: Vector<T>): boolThe example for this item is shown with the ones above: chan-API.salam
Recv
func Recv<T>(c: Chan<T>, ok &: bool): Trecv.The example for this item is shown with the ones above: chan-API.salam
RecvTimeout
func RecvTimeout<T>(c: Chan<T>, ok &: bool, ms: i64): Trecv_timeout.The example for this item is shown with the ones above: chan-API.salam
TryRecv
func TryRecv<T>(c: Chan<T>, ok &: bool): Ttry_recv.The example for this item is shown with the ones above: chan-API.salam
Drain
func Drain<T>(c: Chan<T>): Vector<T>recv, so close the channel before calling it.The example for this item is shown with the ones above: chan-API.salam
Take
func Take<T>(c: Chan<T>, n: i64): Vector<T>n values and returns them as a vector; it stops early when the channel is closed and empty, and waits when neither is true.The example for this item is shown with the ones above: chan-API.salam
Close
func Close<T>(c: Chan<T>)close.The example for this item is shown with the ones above: chan-API.salam
Len
func Len<T>(c: Chan<T>): i64len.The example for this item is shown with the ones above: chan-API.salam
Capacity
func Capacity<T>(c: Chan<T>): i64capacity.The example for this item is shown with the ones above: chan-API.salam
IsClosed
func IsClosed<T>(c: Chan<T>): boolis_closed.The example for this item is shown with the ones above: chan-API.salam
After
func After(ms: i64): Timerms milliseconds.The example for this item is shown with the ones above: chan-Timer.salam
Tick
func Tick(ms: i64): Timerms milliseconds until stopped. A tick is dropped if the channel is full.The example for this item is shown with the ones above: chan-Timer.salam
StopTimer
func StopTimer(t: Timer)The example for this item is shown with the ones above: chan-Timer.salam
Select
func Select<T>(cs: Vector<Chan<T>>, v &: T, ms: i64): i64import chan
import pool
func main:
mut a := chan.Chan {} as chan.Chan<i64>
mut b := chan.Chan {} as chan.Chan<i64>
a.init(2 as i64)
b.init(2 as i64)
mut all := Vector {} as Vector<chan.Chan<i64>>
all.Push(a)
all.Push(b)
p := pool.New(1 as i64, 2 as i64)
pool.Submit(p, (): b.send(42 as i64) end)
mut v := 0 as i64
println chan.Select(all, v, 1000 as i64)
println v
println chan.Select(all, v, 10 as i64)
a.Close()
b.Close()
println chan.Select(all, v, 10 as i64)
pool.Stop(p)
a.Free()
b.Free()
endSelectRecv
func SelectRecv<T>(cs: Vector<Chan<T>>, v &: T, ok &: bool, ms: i64): i64Select with a second result: ok is true when a value arrived, false on timeout or when every channel is closed and empty.The example for this item is shown with the ones above: chan-API.salam
TrySelect
func TrySelect<T>(cs: Vector<Chan<T>>, v &: T): i64Select: returns the index of a ready channel, or minus one when none is ready now.The example for this item is shown with the ones above: chan-API.salam
SelectSend
func SelectSend<T>(cs: Vector<Chan<T>>, v: T, ms: i64): i64try_send.The example for this item is shown with the ones above: chan-API.salam
TrySelectSend
func TrySelectSend<T>(cs: Vector<Chan<T>>, v: T): i64SelectSend: returns the index that took the value, or minus one when no channel has room now.The example for this item is shown with the ones above: chan-API.salam