Standard library · Time and concurrency

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 with chan.Chan {} has no buffer or lock yet and crashes on the first send.
  • Using the value from a failed receive. When ok is false the result is a zero value that means nothing.
  • Telling a timeout from the end. recv_timeout sets ok to false both when the time ran out and when the channel is closed and empty; ask is_closed to know which.
  • Sending a Vector or 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.

chan-guide-loop.salam
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()
end
Outputafter close, send works: false waiting in the buffer: 3 packing A-1001 packing A-1002 packing A-1003 closed and empty: true 0

The 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.

chan-guide-pipeline.salam
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()
end
Outputvalues through the pipeline: 10 sum of squares: 385

The 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.

chan-guide-reply.salam
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()
end
Outputhello, Sara hello, Reza hello, Mina

Many 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.

chan-guide-fanin.salam
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()
end
Outputfrom sensor a: 5 from sensor b: 5 from sensor c: 5

Values 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.

chan-guide-shed.salam
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()
end
Outputaccepted: 3 dropped: 5 waiting: 3 handling request 1 handling request 2 handling request 3 queue empty: true

Between the two extremes are send_timeout and recv_timeout, which wait at most the given number of milliseconds.

If the channel is full or emptySendReceive
Wait as long as it takessendrecv
Wait up to some millisecondssend_timeoutrecv_timeout
Do not wait at alltry_sendtry_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.

chan-API.salam
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()
end
Outputcapacity: 3 len: 0 sent: true queued: 2 first: one true next: two true closed: true send: false left: 0

SelectRecv 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>
A channel of values of type T.
NameTypeDescription
bufT*The buffer of values.
ctli64*The internal state: the head and tail of the queue, the count and whether it is closed.
capi64 = 0The capacity.
zidxi64 = 0The buffer slot holding the type's zero value, for when nothing was received.
musync.MutexThe internal lock.
not_emptysync.CondVarWaking the receivers.
not_fullsync.CondVarWaking the senders.
takensync.CondVarThe signal that a value was taken, on an unbuffered channel.
chan-Chan.salam
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()
end
Outputsum of the squares: 506 true 0 4 false

Init

func Init(capacity: i64)

init

func init(capacity: i64)
Prepares the channel with the given capacity; zero means unbuffered. Call it once, before any thread uses the channel.

The example for this item is shown with the ones above: chan-Chan.salam

Send

func Send(v: T): bool

send

func send(v: T): bool
Sends a value, waiting when there is no room; on an unbuffered channel it waits until a receiver has taken it. If the channel is closed, or is closed while it waits, it returns false.

The example for this item is shown with the ones above: chan-Chan.salam

SendTimeout

func SendTimeout(v: T, ms: i64): bool

send_timeout

func send_timeout(v: T, ms: i64): bool
Like send, but it waits at most ms milliseconds.
chan-Timeout.salam
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()
end
Outputtrue false false hello true after 20 milliseconds: false true a true

SendDeadline

func SendDeadline(v: T, ms: i64, timed: bool): bool

send_deadline

func send_deadline(v: T, ms: i64, timed: bool): bool
The base of the two above: when timed 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): T

recv

func recv(ok &: bool): T
Receives a value, waiting when there is none. When the channel is closed and empty, ok 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): T

recv_timeout

func recv_timeout(ok &: bool, ms: i64): T
Like recv, 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): T

recv_deadline

func recv_deadline(ok &: bool, ms: i64, timed: bool): T
The base of the two above, with the same meaning for timed.

The example for this item is shown with the ones above: chan-Timeout.salam

TrySend

func TrySend(v: T): bool

try_send

func try_send(v: T): bool
Sends if there is room right now; it never waits. On an unbuffered channel it is always false.

The example for this item is shown with the ones above: chan-Timeout.salam

TryRecv

func TryRecv(ok &: bool): T

try_recv

func try_recv(ok &: bool): T
Receives if a value is there right now and sets ok; it never waits.

The example for this item is shown with the ones above: chan-Timeout.salam

Close

func Close()

close

func close()
Closes the channel and wakes every waiting thread. Values already in the buffer can still be received.

The example for this item is shown with the ones above: chan-Chan.salam

IsClosed

func IsClosed(): bool

is_closed

func is_closed(): bool
Whether the channel has been closed.

The example for this item is shown with the ones above: chan-Chan.salam

Len

func Len(): i64

len

func len(): i64
How many values are waiting in the buffer.

The example for this item is shown with the ones above: chan-Chan.salam

Capacity

func Capacity(): i64

capacity

func capacity(): i64
The channel's capacity.

The example for this item is shown with the ones above: chan-Chan.salam

Free

func Free()

free

func free()
Releases the channel's memory. Call it after every thread that uses the channel has been joined.

The example for this item is shown with the ones above: chan-Chan.salam

Timer

struct Timer
A timer whose channel c receives a value when it fires.
NameTypeDescription
cChanThe channel that receives a value each time the timer fires.
canceli64*The flag that tells the timer thread to stop.
argvoid*The argument block of the timer thread.
handlei64 = 0The handle of the timer thread.
chan-Timer.salam
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()
end
Outputtimer fired first: 1 tick value: 1 ticks: 3 stopped early

Functions

New

func New<T>(capacity: i64): Chan<T>
Creates a channel with the given capacity and returns it initialized; zero means unbuffered. Write the type on the result, as in chan.New(4) as chan.Chan<i64>.
chan-API.salam
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()
end
Outputcapacity: 3 len: 0 sent: true queued: 2 first: one true next: two true closed: true send: false left: 0

Send

func Send<T>(c: Chan<T>, v: T): bool
The free-function form of send: 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): bool
The free-function form of send_timeout.

The example for this item is shown with the ones above: chan-API.salam

TrySend

func TrySend<T>(c: Chan<T>, v: T): bool
The free-function form of try_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>): bool
Sends every value of the vector in order and returns false as soon as one send fails; the values after that one were not sent.

The example for this item is shown with the ones above: chan-API.salam

Recv

func Recv<T>(c: Chan<T>, ok &: bool): T
The free-function form of recv.

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): T
The free-function form of recv_timeout.

The example for this item is shown with the ones above: chan-API.salam

TryRecv

func TryRecv<T>(c: Chan<T>, ok &: bool): T
The free-function form of try_recv.

The example for this item is shown with the ones above: chan-API.salam

Drain

func Drain<T>(c: Chan<T>): Vector<T>
Receives values until the channel is closed and empty, and returns them as a vector. It waits like 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>
Receives at most 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>)
The free-function form of close.

The example for this item is shown with the ones above: chan-API.salam

Len

func Len<T>(c: Chan<T>): i64
The free-function form of len.

The example for this item is shown with the ones above: chan-API.salam

Capacity

func Capacity<T>(c: Chan<T>): i64
The free-function form of capacity.

The example for this item is shown with the ones above: chan-API.salam

IsClosed

func IsClosed<T>(c: Chan<T>): bool
The free-function form of is_closed.

The example for this item is shown with the ones above: chan-API.salam

After

func After(ms: i64): Timer
A timer that sends once after ms milliseconds.

The example for this item is shown with the ones above: chan-Timer.salam

Tick

func Tick(ms: i64): Timer
A timer that sends every ms 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)
Stops the timer, joins its thread and frees it. Call it once for every 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): i64
Waits for the first ready channel of a vector of channels without polling: the caller sleeps until a send or a close wakes it. Returns its index and stores the value; -1 when the time in milliseconds runs out (a negative time waits forever), -2 when every channel is closed and empty.
chan-Select.salam
import 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()
end
Output1 42 -1 -2

SelectRecv

func SelectRecv<T>(cs: Vector<Chan<T>>, v &: T, ok &: bool, ms: i64): i64
Select 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): i64
One non-blocking Select: 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): i64
Sends the value to the first channel of the vector that has room, without polling, and returns its index. Returns minus one on timeout and minus two when every channel is closed. It works on buffered channels; an unbuffered channel never has room for try_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): i64
One non-blocking SelectSend: 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