basis/channels/channels-docs.factor

   1 ! Copyright (C) 2007 Chris Double.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.syntax help.markup ;
   4 IN: channels
   5
   6 HELP: <channel>
   7 { $values { "channel" "a channel object" }
   8 }
   9 { $description "Create a channel that can be used for communicating between "
  10 "concurrent processes and threads. " { $link to } " and " { $link from }
  11 " can be used to send and receive data to/from the channel respectively. "
  12 "There can be multiple readers and writers on a channel. If there are "
  13 "multiple readers or writers, only one is selected at random to resume."
  14 }
  15 { $see-also from to } ;
  16
  17 HELP: to
  18 { $values { "value" "an object" }
  19           { "channel" "a channel object" }
  20 }
  21 { $description "Sends an object to a channel. The send operation is synchronous."
  22 " It will block the calling thread until there is a receiver waiting "
  23 "for data on the channel. It will return when the receiver has received "
  24 "the data successfully."
  25 }
  26 { $see-also <channel> from } ;
  27
  28 HELP: from
  29 { $values  { "channel" "a channel object" }
  30            { "value" "an object" }
  31 }
  32 { $description "Receives an object from a channel. The operation is synchronous."
  33 " It will block the calling thread until there is data in the channel."
  34 }
  35 { $see-also <channel> to } ;
  36
  37 ARTICLE: "channels" "Channels"
  38 "The " { $vocab-link "channels" } " vocabulary provides a simple abstraction to send and receive objects." $nl
  39 "Opening a channel:"
  40 { $subsection <channel> }
  41 "Sending a message:"
  42 { $subsection to }
  43 "Receiving a message:"
  44 { $subsection from } ;
  45
  46 ABOUT: "channels"