userdoc_name.dox

来自「一个语言识别引擎」· DOX 代码 · 共 300 行

/**
 * @page name_server The name server protocol

The name server is a program that listens on a known socket-port on
a known machine (we
write socket-ports to distinuish tcp/ip port numbers for sockets, 
from higher-level YARP Ports).
It tracks information about Ports in the YARP Network.
If you know the name
of a Port, you can query the name server to learn how to communicate
with that Port.

The name server maintains a set of records, whose key is a text
string.  The contents are at least hostname, socket number, and
protocol name.  This describes how to contact the port.  There is also
a description of what kinds of connections the port can or is willing
to participate in.  The set of protocols the port can accept an
incoming data connection for are named - this is the ``accept'' set.
The set of protocols the port can create an outgoing data connection
for are also named - this is the ``offer'' set.

For example, suppose you want to communicate with a Port called
``/write''.  The first step is to ask the name server about this
Port.  The name server runs on a known socket-port of a known machine,
listening for tcp connections.
It is usually queried through a library call, but for illustration
purposes we describe
querying it using telnet.  Suppose the name server is running on
machine 192.168.0.3 and listening on socket-port 10000 (we will
discuss a procedure for discovering this information later).
Then we can query the name server about the Port /write as follows:


\verbatim
telnet 192.168.0.3 10000
\endverbatim

The name server should start listening -- if the connection is refused,
something is wrong.  Once the connection is made, type:

\verbatim
NAME_SERVER query /write
\endverbatim

The server will respond with something of the form:

\verbatim
registration name /write ip 5.255.112.227 port 10001 type tcp
*** end of message
\endverbatim

So the Port named /write is listening on the machine with
IP address 5.255.112.227, on port 10001, and it expects TCP
connections.

How do Ports get registered in the same place?  Here's how to create a
(fake) registration
manually (usually it is of course done through a library call).
Telnet to the name server as before, and type:

\verbatim
NAME_SERVER register /write
\endverbatim

The server will respond with something of the form:

\verbatim
registration name /write ip 5.255.112.227 port 10001 type tcp
*** end of message
\endverbatim

The name server takes responsibility for allocating
socket-ports and identifying the machine the Port runs on.

Note that the protocol described here for communicating with the name
server is a YARP2 feature.  YARP1 used a different, binary protocol.
The human-readable protocol has been introduced to make the system
more transparent and easier to step through.

For yarp utilities to correctly discover how
to contact the name server,
there should be a file namer.conf in the directory $HOME/.yarp/conf/
(or in the directory specified by an environment variable $YARP_ROOT)
that looks like this:
\verbatim
192.168.0.3 10000
\endverbatim
This gives the machine and socket-port that the name server is assumed
to be running on.

If this file does not exist, or is incorrect, yarp utilities will
attempt to contact the nameserver using multi-cast broadcasts to
224.2.1.1 port 10001 (this is a YARP2 feature, not available in
YARP1).  If the nameserver is running a machine reachable from
multi-cast, it will respond with its ``true'' tcp address, which will
then be used by the utility.  The configuration file will be updated
automatically for future reference.  The multi-cast protocol is
identical to the normal tcp protocol.  Clients can broadcast
``NAME_SERVER query root'' to trigger the name server to send a record
of the form ``registration name root ip ADDRESS port NUMBER type
CARRIER''.  The ``root'' record is a special record corresponding to
the name server.  Multi-cast broadcasts should not generally be used
by clients to communicate with the name server, since the output of
the name server is not tagged with the recipient, so there is the
potential for cross-talk.



\section name_query query

\verbatim
NAME_SERVER query PORT
\endverbatim

Requests registration information for the named port.  Response is of 
the following form:
\verbatim
registration name PORT ip ADDRESS port NUMBER type CARRIER
*** end of message
\endverbatim
For example:
\verbatim
registration name /write ip 5.255.112.227 port 10001 type tcp
*** end of message
\endverbatim
If there is no registration for the port, the registration line
is omitted, and instead the response is simply:
\verbatim
*** end of message
\endverbatim



\section name_register register

\verbatim
NAME_SERVER register PORT
\endverbatim

Requests creation of registration information for the named port.  
Response is of the following form:
\verbatim
registration name PORT ip ADDRESS port NUMBER type CARRIER
*** end of message
\endverbatim
For example:
\verbatim
registration name /write ip 5.255.112.227 port 10001 type tcp
*** end of message
\endverbatim

Optionally, the user can take responsibility for more, and 
issue commands in one of the following forms:
\verbatim
NAME_SERVER register PORT CARRIER
NAME_SERVER register PORT CARRIER IP
NAME_SERVER register PORT CARRIER IP NUMBER
\endverbatim
Any value (including the port name) can be replaced by ``...'' to leave it 
up to the name-server to choose it.  For example:
\verbatim
NAME_SERVER register ... tcp 127.0.0.1 8080
\endverbatim
Gives something of the form:
\verbatim
registration name /tmp/port/1 ip 127.0.0.1 port 8080 type tcp
*** end of message
\endverbatim
If you choose to set the ip yourself, be careful -- there is the 
possibility of problems with multiple ways to identify the same
machine.  It is best to let the name server choose a name,
which it should do in a consistent way.  If a machine has
multiple ip addresses on multiple networks, that can be 
handled -- see the 
discussion of the ips property in the section on set.
That is important for the purposes of controlling which 
network is used for connections from one port to another.




\section name_unregister unregister

\verbatim
NAME_SERVER unregister PORT
\endverbatim

Removes registration information for the named port.  
Response is of the following form:
\verbatim
*** end of message
\endverbatim


\section name_list list

\verbatim
NAME_SERVER list
\endverbatim

Gives registration information of all known ports.
Response is of the following form:
\verbatim
registration name /write ip 130.251.4.159 port 10021 type tcp
registration name /read ip 130.251.4.159 port 10031 type tcp
registration name /tmp/port/4 ip 130.251.4.159 port 10011 type tcp
registration name /tmp/port/3 ip 130.251.4.52 port 10021 type tcp
registration name /tmp/port/2 ip 130.251.4.52 port 10011 type tcp
registration name /tmp/port/1 ip 130.251.4.159 port 10001 type tcp
*** end of message
\endverbatim



\section name_set set

\verbatim
NAME_SERVER set PORT PROPERTY VALUE1 VALUE2 ...
\endverbatim

The name server can store extra properties of a port, beyond the
bare details associated with registration.  The  set command
is used to do this.  For example, the command:
\verbatim
NAME_SERVER set /write offers tcp udp mcast
\endverbatim
Gets the following response:
\verbatim
port /write property offers = tcp udp mcast
\endverbatim
The get and check commands can then be used to query
such properties.

There are some special properties used by YARP.  Property ``ips''
can list multiple identifiers of a machine.  Property ``offers''
lists carriers that an output port can support.  Propery ``accepts''
lists carriers that an input port can support.





\section name_get get

\verbatim
NAME_SERVER get PORT PROPERTY
\endverbatim

Gets the values of a stored property. For example, 
after the set command example shown earlier, the command:
\verbatim
NAME_SERVER get /write offers
\endverbatim
Returns the following response:
\verbatim
port /write property offers = tcp udp mcast
\endverbatim


\section name_check check

\verbatim
NAME_SERVER check PORT PROPERTY VALUE
\endverbatim

Checks if a stored property can take the given value. For example, 
after the set command example shown earlier, the command:
\verbatim
NAME_SERVER check /write offers tcp
\endverbatim
Returns the following response:
\verbatim
port /write property offers value tcp present true
\endverbatim


\section name_route route

\verbatim
NAME_SERVER route PORT1 PORT2
\endverbatim

Finds a good way to connect an output port to an input port, based
on the carriers they have in common (preferred carriers can optionally
be added to this command in decreasing order of preference) and
which carriers are physically possible (for example, `shmem'
requires ports to be on the same machine, and `local' requires
ports to belong to threads with a shared memory space).
For example, the command:
\verbatim
NAME_SERVER route /write /read
\endverbatim
Returns the following response:
\verbatim
port /write route /read = shmem://read
\endverbatim
Suggesting that shmem is the best carrier to use.


*/