basis/channels/remote/remote-docs.factor

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