basis/channels/remote/remote-docs.factor

   1 ! Copyright (C) 2007 Chris Double.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: channels concurrency.distributed help.markup help.syntax
   4 io.servers strings ;
   5 IN: channels.remote
   6
   7 HELP: <remote-channel>
   8 { $values { "node" "a node object" }
   9           { "id" "the id of the published channel on the node" }
  10           { "remote-channel" remote-channel }
  11 }
  12 { $description "Create a remote channel that acts as a proxy for a "
  13 "channel on another node. The remote node's channel must have been "
  14 "published using " { $link publish } " and the id should be the id "
  15 "returned by " { $link publish }
  16 }
  17 { $examples
  18   { $code "\"localhost\" 9000 <node> \"ID123456\" <remote-channel> \"foo\" over to" }
  19 }
  20 { $see-also publish unpublish } ;
  21
  22 HELP: unpublish
  23 { $values { "id" string }
  24 }
  25 { $description "Stop a previously published channel from being "
  26 "accessible by remote nodes."
  27 }
  28 { $examples
  29   { $code "<channel> publish unpublish" }
  30 }
  31 { $see-also <remote-channel> publish } ;
  32
  33 HELP: publish
  34 { $values { "channel" "a channel object" }
  35           { "id" string }
  36 }
  37 { $description "Make a channel accessible via remote Factor nodes. "
  38 "An id is returned that can be used by another node to use "
  39 { $link to } " and " { $link from } " to access the channel."
  40 }
  41 { $examples
  42   { $code "<channel> publish" }
  43 }
  44 { $see-also <remote-channel> unpublish } ;
  45
  46 ARTICLE: "channels.remote" "Remote Channels"
  47 "Remote channels are channels that can be accessed by other Factor instances. It uses distributed concurrency to serialize and send data between channels."
  48 $nl
  49 "To start a remote node, distributed concurrency must have been started. This can be done using " { $link start-server } "."
  50 $nl
  51 { $snippet "\"myhost.com\" 9001 start-server" }
  52 $nl
  53 "Once the node is started, channels can be published using " { $link publish }
  54 " to be accessed remotely. " { $link publish } " returns an id which a remote node "
  55 "needs to know to access the channel."
  56 $nl
  57 { $snippet "<channel> dup [ from . flush ] curry \"test\" spawn drop publish" }
  58 $nl
  59 "Given the id from the snippet above, a remote node can put items in the channel (where 123456 is the id):"
  60 $nl
  61 { $snippet "\"myhost.com\" 9001 <node> 123456 <remote-channel>\n\"hello\" over to" }
  62 ;
  63
  64 ABOUT: "channels.remote"