Changeset 33935 in project


Ignore:
Timestamp:
04/05/17 00:17:17 (7 weeks ago)
Author:
svnwiki
Message:

Anonymous wiki edit for IP [88.91.29.237]: update from gochan's readme.md

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/4/gochan

    r32760 r33935  
    22[[toc:]]
    33[[http://golang.org/|Go]]-inspired channels for [[http://call-cc.org/|Chicken Scheme]]. Essentially thread-safe
    4 fifo queues that are useful in concurrency and for thread
    5 synchronization. This implementation has largely been inspired by
    6 [[https://gobyexample.com/channels|this Go channel tutorial]].
     4fifo queues that are useful for thread communication and
     5synchronization.
    76
    87chicken-gochan has no egg dependencies.
     
    1211Currently supported:
    1312
    14 * closable channels (they can have limited length)
    15 * receive from multiple channels {{(gochan-receive (list channel1 channel2))}}
    16 * receive timeouts
    17 * {{gochan-select}} syntax
     13* receive and send switch ({{gochan-select}})
     14* timeouts as ordinary receive on a channel
     15* closable channels
     16* load-balancing when multiple channels have data ready
    1817
    1918
    2019=== Comparison to real Go Channels
    21 * all channels have an unlimited buffer
    22 * types are dynamic
     20The API and behaviour largely follows [[http://golang.org/|Go]]'s channel API, with some
     21exceptions:
     22
     23* channels don't have any type information
     24* sending to a channel that gets closed does not panic, it returns
     25  (all sender) immediately with the {{ok}} flag set to {{#f}}.
     26* closing an already closed channel has no effect, and is not an error
     27  ({{gochan-close}} is idempotent).
    2328
    2429
    2530=== API
    26 <procedure> (gochan [item1] [item2] ...)</procedure>
     31<procedure> (gochan capacity)</procedure>
    2732
    28 Construct a {{gochan}} channel initialized with optional items. Each
    29 gochan holds a buffer whose length is limited by memory only.
     33Construct a channel with a maximum buffer-size of {{capacity}}. If
     34{{capacity}} is {{0}}, the channel is unbuffered and all its operations
     35will block until a remote end sends/receives.
     36
     37<procedure> (gochan-select ((chan <-|-> msg [ ok ]) body ...) ...)</procedure>
     38
     39This is a channel switch where you can receive or send to one or more
     40channels, or block until a channel becomes ready. Multiple send and
     41receive operations can be specified. The {{body}} of the first channel
     42to be ready will be executed.
     43
     44Receive clauses, {{((chan <- msg [ok]) body ...)}}, execute {{body}} with
     45{{msg}} bound to the message object, and optionally {{ok}} bound to a flag
     46indicating success ({{#t}}) or not ({{#f}} if channel was closed).
     47
     48Send clauses, {{((chan -> msg [ok]) body ...)}}, execute {{body}} after
     49{{msg}} has been sent to a receiver, successfully buffered onto the
     50channel, or if channel was closed. Again, the optional variable name
     51{{ok}}, flags whether this was successful.
     52
     53Only one clause {{body}} will get executed. {{gochan-select}} will block
     54until a clause is ready. A send/recv on a closed channel yields the
     55{{#f}} message and a {{#f}} {{ok}} immediately (this never blocks).
     56
     57Here's an example:
     58
     59<enscript highlight="scheme">   
     60(gochan-select
     61 ((chan1 -> msg ok) (if ok
     62                        (print "chan3 says " msg)
     63                        (print "chan3 was closed!")))
     64 ((chan2 <- 123) (print "somebody will get/has gotten 123 on chan2") ))
     65</enscript>
     66
     67{{gochan-select}} returns the return-value of the executed clause's
     68body.
    3069
    3170<procedure> (gochan-send chan msg)</procedure>
    3271
    33 Add msg to chan's message buffer. This will "awaken" a single thread,
    34 if any, waiting for messages on chan. It is an error to send to a
    35 closed channel.
     72This is short for {{(gochan-select ((chan <- msg)))}}.
    3673
    37 <procedure> (gochan-receive chans [timeout/seconds])</procedure>
     74<procedure> (gochan-recv chan)</procedure>
    3875
    39 {{chans}} is a single gochan or a list of gochans. Pops next msg from
    40 any of chans' buffers in a thread-safe manner, if possible. Otherwise,
    41 if channel is empty, wait for a {{gochan-send}} from another thread. If
    42 timeout is supplied and is reached, or all channels are empty and
    43 closed, an error is thrown.
    44 
    45 If multiple channels in chans have messages available, the message
    46 from the first channel is popped first.
    47 
    48 If you have multiple threads waiting messages from the same gochan,
    49 the order in which threads receive messages is unspecified (but each
    50 message is received only once).
    51 
    52 <procedure> (gochan-receive* chans timeout/seconds)</procedure>
    53 
    54 Like {{gochan-receive}}, but doesn't error out. Instead, it returns:
    55 {{#f}} for all channels closed, {{#t}} for timeout and {{(list <msg>)}} on
    56 success (distinguishable from a {{#f}} or {{#t}} message).
     76This is short for {{(gochan-select ((chan -> msg)))}}.
    5777
    5878<procedure> (gochan-close chan)</procedure>
    5979
    60 Close channel. It is an error to send to a closed channel. It is an
    61 error to receive from an empty and closed channel.
     80Close the channel. Sending to or receiving from a closed channel will
     81immediately return a {{#f}} message with the {{ok}} flag set to {{#f}}. Note
     82that this will unblock ''all'' receivers and senders waiting for an
     83operation on {{chan}}.
    6284
    63 <procedure> (gochan-closed? chan)</procedure>
     85<procedure> (gochan-after duration/ms)</procedure>
    6486
    65 Closed predicate.
     87Return a {{gochan}} that will "send" a single message after
     88{{duration/ms}} milliseconds of its creation. The message is the
     89{{(current-milliseconds)}} value at the time of the timeout (not when
     90the message was received).
    6691
    67 <procedure> (gochan-for-each chans proc)</procedure>
     92<procedure> (gochan-tick duration/ms)</procedure>
    6893
    69 Call {{(proc <msg>)}} for each msg in chan ({{proc}} must unfortunately
    70 have side-effects). Returns {{(void)}} when chan is closed.
     94Return a {{gochan}} that will "send" a message every {{duration/ms}}
     95milliseconds. The message is the {{(current-milliseconds)}}
     96value at the time of the tick (not when it was received).
    7197
    72 <procedure> (gochan-fold chans proc)</procedure>
     98<procedure> (go body ...)</procedure>
    7399
    74 Like a normal fold, but fold over chans's messages.
     100Starts and returns a new srfi-18 thread. Short for {{(thread-start!
     101(lambda () body ...))}}.
    75102
    76 <syntax> (gochan-select (<chan> <var> body ...) ... (<timeout/seconds> body ...))</syntax>
    77103
    78 Convenience syntax for handling incoming messages from different
    79 gochans differently. Used as in [[http://golang.org/|Go]], typically:
    80 
    81 <enscript highlight="scheme">
    82 (gochan-select
    83  (chan1 msg (error "from c1" msg))
    84  (chan2 obj (list  "from c2" obj))
    85  (1 (error "waited one second, but got nothing!")))
    86 </enscript>
    87 
    88 It is an error to specify multiple timeouts. {{gochan-select}} returns
    89 the associated channel's body return-value.
     104=== TODO
     105* Add an {{else}} clause ([[http://golang.org/|Go]]'s {{default}}) to {{gochan-select}}
    90106
    91107
Note: See TracChangeset for help on using the changeset viewer.