/**
\page terms Definition of terms

\tableofcontents

The YARP library supports transmission of a stream of
user data across
various protocols -- TCP, UDP, MCAST (multi-cast), shared memory --
insulating a user of the library from the
idiosyncratic details of the network technology used.  We call these
these low-level protocols the ``Carriers'', to distinguish them from
the higher-level protocols we will be concerned with here.

For the purposes of YARP, communication takes place through
``Connections'' between named entities called ``Ports''.
These form a directed graph, the ``YARP Network'', where Ports are the nodes,
and Connections are the edges.

Each Port is assigned a unique name, such as ``/motor/wheels/left''.
Every Port is registered by name with
a ``name server''.  The goal is to ensure that if you know the name
of a Port, that is all you need in order to be able to
communicate with it from any machine.

The purpose of Ports is to move ``Content'' (sequences of bytes representing
user data) from
one thread to another (or several others) across process and machine
boundaries.  The flow of data can be manipulated and monitored
externally (e.g. from the command-line) at run-time.  In other words,
the edges in the YARP Network are entirely mutable.

A Port can send Content to any number of other Ports.  A
Port can receive Content from any number of other Ports.  If one
Port is configured to send Content to another Port, they are
said to have a Connection.  Connections can be freely added or
removed, and may use different Carriers.

The YARP name server is a server that tracks information about ports.
It indexes this information by name, playing a role analogous to
DNS on the internet.
To communicate with a port, the properties of that port need to be
known (the machine it is running on, the socket it is listening on,
the carriers it supports).  The YARP name server offers a convenient
place to store these properties, so that only the name of the port is
needed to recover them.


Here are the specifications available in this document:

\li Properties of a YARP network.

\li Properties of the YARP utility.

\li Properties of the YARP name server and the protocol used
for communicating with it.

\li Properties of ports and the protocol used
for communicating with them.



\section term_prop Properties of a YARP network

A YARP network consists of the following entities: a set of
ports, a set of connections, a set of names, a name server, and a set
of registrations.

\li Every port has a unique name.

\li Every connection has a source port and a target port.

\li Each port maintains a list of all connections for which it
is the target port.

\li Each port maintains a list of all connections for which it
is the source port.

\li There is a single name server in a YARP network.

\li The name server maintains a list of registrations.  Each
registration contains information about a single port, identified
by name.



Communication within a YARP network can occur between two ports,
between a port and the name server, between a port and an
external entity, and between the name server and an external entity.



\li Communication between two ports occurs if and only if there
is a connection between them.  That communication uses the
``connection protocol''.

\li Connections involving a port can be created, destroyed, or
queried by communication between an external entity and that port.
This is done by sending ``port commands'' using the YARP
connection protocol.

\li Ports communicate with the name server using the
``YARP name server protocol''.  Such communication is needed
to create, remove, and query registrations.

\li External entities can also use the YARP name server protocol
to query the name server.




The standard YARP companion utility can be used to create a
name server, and also to act as an external entity for querying and
modifying the YARP network.

- \ref yarp
- \ref companion_use
- \ref name_server
- \ref data_rep

*/
