SYNOPSIS
#include <nng/nng.h>
int nng_device(nng_socket s1, nng_socket s2);DESCRIPTION
The nng_device() function forwards messages received from one
socket s1 to another socket s2, and vice versa.
This function is used to create forwarders, which can be used to create complex network topologies to provide for improved horizontal scalability, reliability, and isolation.
The nng_device() function does not return until one of the sockets
is closed.
Reflectors
One of the sockets may be passed the special value -1 (cast to an,
nng_socket of course).
If this is the case, then the other socket must be valid, and must be
a protocol that is bidirectional and can peer with itself (such as
pair or
bus.)
In this case the device acts as a reflector or loop-back device,
where messages received from the valid socket are merely returned
back to the sender.
Forwarders
When both sockets are valid, then the result is a forwarder or proxy. In this case sockets s1 and s2 must be “compatible” with each other, which is to say that they should represent the opposite halves of a two protocol pattern, or both be the same protocol for a single protocol pattern. For example, if s1 is a pub socket, then s2 must be a sub socket. Or, if s1 is a bus socket, then s2 must also be a bus socket.
Operation
This nng_device() function puts each socket into raw mode
(see NNG_OPT_RAW), and then moves messages
between them.
When a protocol has a backtrace style header, routing information is
added as the message crosses the forwarder, allowing replies to be
returned to requestors, and responses to be routed back to surveyors.
Additionally, some protocols have a maximum time-to-live to protect
against forwarding loops and especially amplification loops.
In these cases, the default limit (usually 8), ensures that messages will
self-terminate when they have passed through too many forwarders,
protecting the network from unlimited message amplification that can arise
through misconfiguration.
This is controlled via the NNG_OPT_MAXTTL
option.
| Not all protocols have support for guarding against forwarding loops, and even for those that do, forwarding loops can be extremely determintal to network performance. |
| Devices (forwarders and reflectors) act in best effort delivery mode only. If a message is received from one socket that cannot be accepted by the other (due to backpressure or other issues), then the message is discarded. |
| Use the request/reply pattern, which includes automatic retries by the requestor, if reliable delivery is needed. |
RETURN VALUES
This function returns 0 on success, and non-zero otherwise.
ERRORS
NNG_ECLOSED-
At least one of the sockets is not open.
NNG_ENOMEM-
Insufficient memory is available.
NNG_EINVAL-
The sockets are not compatible, or are both invalid.