gochan
  1. gochan
    1. Dependencies
    2. Development Status
    3. Comparison to real Go Channels
    4. Comparison to core.async
    5. API
    6. Samples
    7. TODO

Go-inspired channels for Chicken Scheme (Chibi Scheme might work too). Essentially thread-safe fifo queues that are useful for thread communication and synchronization.

Dependencies

Development Status

Currently supported:

Source code can be found here.

Comparison to real Go Channels

The API and behaviour largely follows Go's channel API, with some exceptions:

Comparison to core.async

Honestly, I wish I had stolen the core.async API instead of the Go channel API since that's already a LISP, but here is what we have for now:

API

[procedure] (gochan capacity)

Construct a channel with a maximum buffer-size of capacity. If capacity is 0, the channel is unbuffered and all its operations will block until a remote end sends/receives.

[syntax] (gochan-select ((chan <-|-> msg [ fail ]) body ...) ... [(else body ...])

This is a channel switch that will send or receive on a single channel, picking whichever clause is able to complete soonest. If no clause is ready, gochan-select will block until one does, unless else is specified which will by execute its body instead of blocking. Multiple send and receive clauses can be specified interchangeably. Note that only one clause will be served.

Here's an example:

    
(gochan-select
  ((chan1 -> msg fail) (if fail (print "chan1 closed!") (print "chan1 says " msg)))
  ((chan2 -> msg fail) (if fail (print "chan2 closed!") (print "chan2 says " msg))))

Receive clauses, ((chan -> msg [fail]) body ...), execute body with msg bound to the message object and fail bound to a flag indicating failure. Receiving from a closed channel immediately completes with this fail flag set to non-#f.

Send clauses, ((chan <- msg [fail]) body ...), execute body after msg has been sent to a receiver, successfully buffered onto the channel, or if channel was closed. Sending to a closed channel immediately completes with the fail flag set to #f.

A send or receive clause on a closed channel with no fail-flag binding specified will immediately return (void) without executing body. This can be combined with recursion like this:

    
;; loop forever until either chan1 or chan2 closes
(let loop ()
   (gochan-select
    ((chan1 -> msg) (print "chan1 says " msg) (loop))
    ((chan2 <- 123) (print "chan2 got  " 123) (loop))))

Or like this:

    
;; loop forever until chan1 closes. replacing chan2 is important to avoid busy-wait!
(let loop ((chan2 chan2))
  (gochan-select
   ((chan1 -> msg)      (print "chan1 says " msg) (loop chan2))
   ((chan2 -> msg fail) (if fail
                            (begin (print "chan2 closed, keep going")
                                   ;; create new forever-blocking channel
                                   (loop (gochan 0)))
                            (begin (print "chan2 says " msg)
                                   (loop chan2))))))

gochan-select returns the return-value of the executed clause's body.

To do a non-blocking receive, you can do the following:

    
(gochan-select ((chan1 -> msg fail) (if fail #!eof msg))
               (else 'eagain))
[procedure] (gochan-select* chans)

This procedure allows selecting channels that are chosen programmatically. It takes input that looks like this:

(gochan-select `((,chan1 meta1)
                 (,chan2 meta2 message)
                 (,chan3 meta3) ...))

It returns three values, msg fail meta, where msg is the message that was sent over the channel, fail is true if the channel was closed and false otherwise, and meta is the datum supplied in the arguments.

For example, if a message arrived on chan3 above, for example, meta would be 'meta3 in that case. This allows you to see which channel a message came from (i.e. if you supply meta data that is the channel itself)

[procedure] (gochan-send chan msg)

This is short for (gochan-select ((chan <- msg fail) (values #f fail #t))).

[procedure] (gochan-recv chan)

This is short for (gochan-select ((chan -> msg fail) (values msg fail #t))).

[procedure] (gochan-close chan [fail-flag])

Close the channel. Note that this will unblock existing receivers and senders waiting for an operation on chan with the fail-flag set to a non-#f value. All future receivers and senders will also immdiately unblock in this way, so watch out for busy-loops.

The optional fail-flag can be used to specify an alternative to the default #t. As this value is given to all receivers and senders of chan, the fail-flag can be used as a "broadcast" mechanism. fail-flag cannot be #f as that would indicate a successful message transaction.

Closing an already closed channel will results in its fail-flag being updated.

[procedure] (gochan-after duration/ms)

Returns a gochan that will "send" a single message after duration/ms milliseconds of its creation. The message is the (current-milliseconds) value at the time of the timeout (not when the message was received). Receiving more than once on an gochan-after channel will block indefinitely or deadlock the second time.

    
(gochan-select
 ((chan1 -> msg)                (print "chan1 says " msg))
 (((gochan-after 1000) -> when) (print "chan1 took too long")))

You cannot send to or close a timer channel. These are special records that contain information about when the next timer will trigger. Creating timers is a relatively cheap operation, and unlike golang.time.After, may be garbage-collected before the timer triggers. Creating a timer does not spawn a new thread.

[procedure] (gochan-tick duration/ms)

Return a gochan that will "send" a message every duration/ms milliseconds. The message is the (current-milliseconds) value at the time of the tick (not when it was received).

See tests/worker-pool.scm for an example of its use.

[syntax] (go body ...)

Starts and returns a new srfi-18 thread. Short for (thread-start! (lambda () body ...)).

Samples

TODO