distributed_channels.tex

\chapter{Distributed Channels}\label{dchannels}

Remote Channels are distributed channels that allow you to access
channels in separate Factor instances, even on different machines on
the network. 

\wordtable{
\vocabulary{channels.remote}
\ordinaryword{<remote-channel>}{<remote-channel> ( node id -- remote-channel )}
\ordinaryword{publish}{publish ( channel -- id )}
}

A channel can be made accessible by remote Factor nodes using the
\texttt{publish} word. Given a channel this will return a unique
identifier that can be used by remote nodes to use the channel. For
example:

\begin{verbatim}
USING: fry threads channels channels.remote ;

: (counter) ( channel n -- )
  [ swap to ] [ 1 + (counter) ] 2bi ;
    
: counter ( channel -- )
  2 (counter) ;    

<channel> dup '[ _ counter ] "counter" spawn drop publish .
 => 12345678901234567890.....
\end{verbatim}

Remote channels are implemented using
distributed concurrency so you must start a node on the Factor
instance you are using. This is done with 'start-node' giving the
hostname and port in an 'addrspec'.

\wordtable{
\vocabulary{concurrency.distributed}
\ordinaryword{start-node}{start-node ( addrspec -- )}
}

\begin{verbatim}
USING: io.sockets io.servers concurrency.distributed ;
"localhost" 9000 <inet> start-node
\end{verbatim}

Once this is done all published channels become available. Note that
the hostname and port must be accessible by the remote machine so it
can connect to send the data you request.

From a remote node you can create a \texttt{<remote-channel>} which contains
the hostname and port of the node containing the channel, and the identifer
of that channel.

You can use `from' and `to' on the remote channel exactly as you can
on normal channels. The data is marshalled over the network using the
serialization library.  

Run the following on a different node to use the services of the first node,
replacing '1234...' with the published id from the previous example.

\begin{verbatim}
USING: io.sockets channels channels.remote concurrency.distributed ;

"localhost" 9001 <inet> start-node

"localhost" 9000 <inet> 1234... <remote-channel> from .
\end{verbatim}

Note that you must start a node using 'start-node' on all nodes that want to
use remote channels.

One way of setting up remote channel services is to serialize an instance of a \texttt{<remote-channel>} for a published channel and make it available on an HTTP server. The remote nodes can retrieve this via HTTP, deserialize it and use it. You can test this on a local machine by running two factor instances. In instance 1:

\begin{verbatim}
USING:
  fry 
  io.encodings.binary
  threads 
  concurrency.distributed 
  channels  
  channels.remote 
  serialize 
;

"localhost" 9000 <inet> start-node 

: (counter) ( channel n -- )
  [ swap to ] [ 1 + (counter) ] 2bi ;
    
: counter ( channel -- )
  2 (counter) ;    

<channel> dup '[ _ counter ] "counter" spawn drop 
publish local-node get insecure>> swap <remote-channel>
"counter.ser" binary [ serialize ] with-file-writer
\end{verbatim}

This creates a channel that returns incrementing integer numbers, as per our previous examples. A \texttt{<remote-channel>} is created with the published identifier for this channel and our node address. This is serialized to a file called ``counter.ser''. A remote node can deserialize this file and use it to access the channel immediately. In factor instance 2:

\begin{verbatim}
USING: 
  io.encodings.binary
  threads 
  concurrency.distributed 
  channels 
  channels.remote 
  serialize 
;

"localhost" 9001 <inet> start-node 
"counter.ser" binary [ deserialize ] with-file-reader
dup from .
 => 2
dup from .
 => 3
\end{verbatim}