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