section-port.tex

一个语言识别引擎

\chapter{Port commands}

Every port is always available for new connections from external
entities -- to request that new connections between ports be created,
old connections be removed, to inquire after status, etc.
%
The protocol used for communicating with a port is layered on top of the
protocol described in the previous section.  Any carrier can be used.
The ``payload data'' is as follows:

\begin{itemize}

\item We send an 8 byte header: \packet{0,0,0,0, `\twiddle', CHAR, 0, 1.}

\item CHAR is a character that identifies what the message is about.

  \begin{itemize}
    
  \item CHAR = `d': this header is used to signal that user data is
  arriving next, as opposed to a port command
    
  \item CHAR = anything else: this signals that a port command
    follows.

  \end{itemize}

\item for the port command case (CHAR = 0) the remainder of the message 
  is interpreted as a string S.

  \begin{itemize}
   \item S begins with `/', e.g. `/read': this is a request to add a
   Connection to the named InputPort.

   \item S begins with `!', e.g. `!/read': this is a request to remove
   a Connection to the named InputPort.

   \item S begins with `\twiddle', e.g. `\twiddle/read': this is a
   request to remove a Connection from the named OutputPort.

   \item S is `*': this is a request for the port to dump information
     about what it is connected to.

   \item S is `q': the specific connection that the command is received on
   should now shut down.
  \end{itemize}

\end{itemize}

\noindent
Alternatively, with the ``text'' carrier, we send a string terminated
in `$\backslash$n'.  This is the string S.  The first letter is copied
to be CHAR.



\section{YARP URIs}

Port names in YARP can contain multiple special elements.
We've seen names such as ``/write''.  We can also have
names such as ``udp://write'' which means ``connect
to the port named /write using the udp carrier''.

We can also prepend a network selector of the form
``/net=NETNAME/''.  For example, a name such as
``udp://net=196/write'' means ``connect to the 
port named /write using the udp carrier, and make the
connection on the network with ip addresses beginning with
196''.
%
This is useful in scenarios with multiple networks, where it may be
desirable to route connections through particular networks (for
example, to devote a network to time-critical traffic).  This
functionality is supported primarily with the help of the name server.
The ip it reports for a machine is usually a reasonable default, but
the user can choose using ``net='' to request a name on a particular
network.

Symbolic network names can be configured.  This process is not yet
specified.  You can do it right now by setting properties of a fake
port called ``networks'' (no leading slash), where the properties are
symbolic names and their values are the numeric network IP prefix.
But this process will change.

%% How should multiple networks work?  Currently in YARP1, a port is
%% associated with a particular network.  If two ports are on different
%% networks, they can't communicate, even if there is connectivity
%% (I think).

%% It would seem more desirable to associate the choice of network,
%% if there is a choice, with the edges (connections) and not the
%% nodes (ports).

%% Let's require that all nodes can reach the name server and vice
%% versa.

%% Single-hop network choice for tcp and udp can be made by selecting one
%% of a choice of IPs for the target.  Could add a connection attribute
%% ``over 192.*'' as a way to choose net?  Or text names.

%% Done!


\section{Carriers supported}

An implementation of YARP2 must support at least the ``tcp'' carrier.
Other carriers that may be supported:
``text'', ``udp'', ``mcast'', ``shmem'', ``qnx'', ``local''.

As a place to start an implementation, the ``text'' carrier is very
simple to implement, and can masquerade as ``tcp'' for the purposes
of initial handshaking.

To see this, get the ``netcat'' program (available as debian package
of the same name).  In one terminal, run:
%
\begin{code}
nc -l -p 9000
\end{code}
%
This starts a tcp listener on socket-port 9000, and prints out
any data that arrives there.  Then tell the name server to
create an entry for this listener, and tag it as accepting text:
%
\begin{code}
yarp name register /nc tcp ... 9000
yarp name set /nc accepts text
\end{code}
%
Now lets write some data to that port.
%
\begin{code}
yarp write /write text://nc
\end{code}
%
Type something in, such as ``hello world'', and hit return.
On the terminal running {\tt nc} (netcat) you should see:
%
\begin{code}
CONNECT /write
d
0 "hello world"
\end{code}
%
This is what text mode looks like, for the particular
data type used by yarp read and write (``bottles'').  
As we saw in an earlier section, we can also write to ports in text mode.
And if we were to restart nc and then try the following:
%
\begin{code}
yarp connect text://nc /foo
\end{code}
%
\begin{code}
CONNECT external
/foo
\end{code}
%
This is what a command to connect looks like in YARP2.  If we omit the
``text:/'' then the tcp carrier may be used, which is compatible with YARP1
but is a bit less trivial to work with.  Once our YARP implementations
are up to date, the default command carrier will be switched to text.