/**
\page carrier_config Configuring YARP Connections

\tableofcontents

Every YARP connection has a specific type of carrier associated
with it.  This corresponds roughly to the "transport" used to
carry data.  For example there is the tcp carrier, the udp carrier,
the mcast (multi-cast) carrier.  For each transport, there can
be several variants of carrier.  For example, across tcp, there
can be the basic binary-mode tcp carrier, or the text (text-mode)
carrier, or the fast_tcp carrier which takes some shortcuts for
speed.

Before using carriers other than the default, please do make sure you
understand the performance of your network and check that it is
configured well - see \ref yarp_cluster.

Here we look at configuration issues that arise for individual
carriers.

\if MAN_PAGE_COND
\else
- \ref carrier_config_tcp
- \ref carrier_config_udp
- \ref carrier_config_mcast
- \ref carrier_config_shmem
- \ref carrier_config_local
- \ref carrier_config_text
- \ref carrier_config_text_ack
- \ref carrier_config_fast_tcp
- \ref carrier_config_http
\endif

Optional carriers:
\li \ref carrier_config_mpi
\li \ref carrier_config_mjpeg
\li \ref carrier_config_xmlrpc
\li \ref carrier_config_tcpros
\li \ref carrier_config_bayer


\section carrier_config_tcp tcp carrier

This is the default carrier for YARP connections.  It doesn't
really need much configuration.  For two ports, /src and /dest,
you can establish a tcp connection between them by typing:
\verbatim
yarp connect /src /dest
\endverbatim
or equivalently:
\verbatim
yarp connect /src /dest tcp
\endverbatim

If the two ports are on separate computers connected by multiple
networks, the network the connection uses may not be the one you'd
prefer.  If you want to control this, you can prepend
"/net=IP-PREFIX/" to the target port name.  For example, a name such
as "/net=196/write" means "connect to the port named /write using the
network with ip addresses beginning with 196''.  See \ref yarp_uri.

\section carrier_config_udp udp carrier

You can establish a UDP connection between two ports /src and /dest by
typing:
\verbatim
yarp connect /src /dest udp
\endverbatim

The udp carrier is unreliable (by the nature of the underlying UDP
protocol).  However, on a local network under controlled conditions
UDP can be a very efficient method for moving data.

The udp carrier is unidirectional; it should be used for streaming
messages rather than RPC (remote procedure call) send/reply sequences.

YARP will discard messages with corrupted, missing, duplicated, or
out-of-order parts, so the only problem you should have is messages
simply failing to arrive.

If you have multiple networks, you can control which networks
individual connections use with the same method described for
the \ref carrier_config_tcp "tcp carrier".

The steps described in \ref yarp_cluster are very important
if you will be sending large YARP messages using udp.

Large messages are broken into a series of datagrams.  You can control
the size of those datagrams in bytes by setting the environment
variable YARP_DGRAM_SIZE (to control both udp and multicast together)
or YARP_UDP_SIZE (to control just udp datagram size).  The right
setting for this number depends a lot on what you want to do.  It is
worth experimenting across quite a large range, say from 5000 to
120000 or more.

\section carrier_config_mcast mcast (multicast) carrier

You can establish a multicast connection between two ports /src and /dest
by typing:
\verbatim
yarp connect /src /dest mcast
\endverbatim

CAREFUL: multicast is not supported by all all network hardware, and
even when it is, support can be a bit hit-and-miss.

For multiple ports reading from the same source, YARP will map
these logical connections to a single multicasting source.

The mcast carrier is unreliable (by the nature of the underlying
multicast protocol).  However, on a local network under controlled
conditions multicast can be a very efficient method for moving data.

The mcast carrier is unidirectional; it should be used for streaming
messages rather than RPC (remote procedure call) send/reply sequences.

YARP will discard messages with corrupted, missing, duplicated, or
out-of-order parts, so the only problem you should have is messages
simply failing to arrive.

If you have multiple networks, you can control which networks
individual connections use with the same method described for
the \ref carrier_config_tcp "tcp carrier".

The steps described in \ref yarp_cluster are very important
if you will be sending large YARP messages using mcast.

Large messages are broken into a series of datagrams.  You can control
the size of those datagrams in bytes by setting the environment
variable YARP_DGRAM_SIZE (to control both udp and multicast together)
or YARP_MCAST_SIZE (to control just multicast datagram size).  The
right setting for this number depends a lot on what you want to do.
It is worth experimenting across quite a large range, say from 5000 to
120000 or more.

\section carrier_config_shmem shmem (shared memory) carrier

You can establish a shared memory connection between two
ports /src and /dest by typing:
\verbatim
yarp connect /src /dest shmem
\endverbatim

\note Such connections will not work unless the source and
destination ports are on the same machine.  That is the nature
of shared memory.

The author of this documentation is not aware of any configuration
options for this carrier.


\section carrier_config_local local (within-process) carrier

You can establish a connection via shared process memory between two
ports /src and /dest by typing:
\verbatim
yarp connect /src /dest local
\endverbatim

\note Such connections will not work unless the source and
destination ports belong to the same process.

For ports that are in control of message allocation and reuse
(i.e. BufferedPort ports), this is a very efficient carrier.
The messages held by source and destination ports are placed
into a merged pool with zero copies needed.

\section carrier_config_text text (text-mode across tcp) carrier

You can establish a text-mode connection between two
ports /src and /dest by typing:
\verbatim
yarp connect /src /dest text
\endverbatim

This is a reliable TCP connection.  This is useful if the destination port
is not actually a YARP port, but a socket being read by a non-YARP
program.  Text-mode messages are particularly easy to read
(see \ref yarp_without_yarp).

This type of connection does not contain acknowledgements to the
sender of data received.  If this is a problem, use the
\ref carrier_config_text_ack "text_ack carrier".

\section carrier_config_text_ack text_ack (text-mode across tcp with acknowledgement) carrier

You can establish a text-mode connection between two
ports /src and /dest by typing:
\verbatim
yarp connect /src /dest text_ack
\endverbatim

This is a reliable TCP connection.  This is useful if the destination port
is not actually a YARP port, but a socket being read by a non-YARP
program.  Text-mode messages are particularly easy to read
(see \ref yarp_without_yarp).

This type of connection has acknowledgements to the
sender of data received, unlike the
\ref carrier_config_text "text carrier".


\section carrier_config_fast_tcp fast_tcp (tcp without acknowledgement) carrier

You can establish a binary-mode tcp connection without acknowledgements
between two ports /src and /dest by typing:
\verbatim
yarp connect /src /dest fast_tcp
\endverbatim

This can be useful to get a bit more speed in cases where flow is
producer-limited, not consumer-limited.  In general though it
is safer to use the regular \ref carrier_config_tcp "tcp carrier".

\section carrier_config_http http carrier

This is a carrier for use from web browsers.  It is not intended
for port-to-port connections.  See \ref yarp_http
for details.

\section carrier_config_mjpeg mjpeg (mjpeg-over-http) carrier

This carrier is for transporting images only.  It is handy for
reading directly from IP cameras, or streaming images to a
browser (most modern browsers can directly render mjpeg-over-http
streams).  See \ref yarp_http_recv_images.

\verbatim
yarp connect /src /dest mjpeg
\endverbatim

To compile this carrier, turn on YARP_COMPILE_CARRIER_PLUGINS and then
ENABLE_yarpcar_mjpeg_carrier in CMake.  There will be an extra CMake
option called MJPEG_AUTOCOMPRESS.  If turned on, this carrier will
deliver images of standard YARP image format to ports.  If turned
off, this carrier will deliver blobs that can be read by
yarp::os::ManagedBytes or yarp::os::Bottle.  See
yarp::mjpeg::MjpegDecompression for helper functions.
The motivation for disabling automatic decompression is to reduce
load for clients that need to read images only occasionally.

\section carrier_config_xmlrpc xmlrpc carrier

This carrier transmits and receives messages in XMLRPC format.

\verbatim
yarp connect /src /dest local
\endverbatim

Messages are automatically converted to and from Bottle-compatible
format.  Here is the mapping used:
 \li XMLRPC int = Bottle int
 \li XMLRPC string = Bottle string
 \li XMLRPC double = Bottle double
 \li XMLRPC array = Bottle list
 \li XMLRPC struct = Bottle list

Both arrays and structures in XMLRPC are mapped to Bottle lists.
Structures are mapped to a list with the tag "dict" prepended,
followed by sublists with key-value mappings:
\verbatim
  (dict (key1 val1) (key2 val2))
\endverbatim

The yarp::os::Bottle find/findGroup/check methods will work fine on
such lists, or you could populate a Property object if you want fast
look-up.

If you want to convert a Bottle list that may start with the
string "dict" or "list", prepend the keyword "list".
\verbatim
  (list ...)
\endverbatim
That keyword will be silently consumed, and will guarantee
that an XMLRPC array is produced.

XMLRPC messages that start with a string may be treated as an
administrative message (and not passed on to the client reading
from a port) if the initial string is one of the following:
 \li publisherUpdate
 \li requestTopic
 \li getPid
 \li getBusInfo

This is for ROS compatibility (see \ref yarp_with_ros).


\section carrier_config_tcpros tcpros carrier

This carrier is for interoperations with ROS.
See \ref yarp_with_ros and http://www.ros.org/wiki/ROS/TCPROS


\section carrier_config_bayer bayer carrier

The bayer carrier converts bayer images to rgb images on the
receiver's side of a connection.  It is a modifying carrier,
and so can be used in combination with other carriers.
For example, suppose port /grabber is streaming bayer images.
For concreteness, here's a test program to do that (back.ppm is
an arbitrary test image in PPM format):
\verbatim
  yarpdev --device fakeFrameGrabber --src back.ppm --bayer --name /grabber
\endverbatim
Suppose we start an image viewer and look at the stream from
/grabber, using (for example) udp:
\verbatim
  yarpview /view
  yarp connect /grabber /view udp
\endverbatim
We will see a monochrome, speckled image (a bayer image).  We
can now reconnect with a connection that is configured to
"debayer" the image on the receiver side:
\verbatim
  yarp connect /grabber /view udp+recv.bayer
\endverbatim
We should now see a color image.  To use a downsampling debayer
algorithm, we can do:
\verbatim
  yarp connect /grabber /view udp+recv.bayer+size.half
\endverbatim
or equivalently:
\verbatim
  yarp connect /grabber udp+recv.bayer+size.half://view
\endverbatim

If we are reading from a source using a non-default bayer
color ordering, we can also specify this with the "order"
carrier modifier:
\verbatim
  yarp connect /grabber /view udp+recv.bayer+order.bggr
\endverbatim
This says the first pixel on the first row is a blue color,
followed by green.  On the second row, the first pixel
is green, followed by red.

Debayer filters from libdc1394 are supported, and can be
specified using the "method" carrier modifier:
\verbatim
  yarp connect /grabber /view tcp+recv.bayer+method.vng
\endverbatim
Available methods: bilinear, hqlinear, downsample, vng, ahd, nearest,
simple.

*/
