NAME

       nng_device - message forwarding device

SYNOPSIS

           #include <nng/nng.h>

           int nng_device(nng_socket s1, nng_socket s2);

           void nng_device_aio(nng_aio *aio, nng_socket s1, nng_socket s2);

DESCRIPTION

       The nng_device() and nng_device_aio() functions forward messages received from one socket s1 to another
       socket s2, and vice versa.

       These functions are used to create forwarders, which can be used to create complex network topologies to
       provide for improved horizontal scalability, reliability, and isolation.

       Only raw mode sockets may be used with this function. These can be created using _raw forms of the
       various socket constructors, such as nng_req0_open_raw().

       The nng_device() function does not return until one of the sockets is closed. The nng_device_aio()
       function returns immediately, and operates completely in the background.

   Reflectors
       One of the sockets passed may be an unopened socket initialized with the NNG_SOCKET_INITIALIZER special
       value. If this is the case, then the other socket must be valid, and must use 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 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
       The nng_device() function moves messages between the provided sockets.

       When a protocol has a backtrace style header, routing information is present in the header of received
       messages, and is copied to the header of the output bound message. The underlying raw mode protocols
       supply the necessary header adjustments to add or remove routing headers as needed. This allows replies
       to be returned to requesters, and responses to be routed back to surveyors.

       The caller of these functions is required to close the sockets when the device is stopped.

       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.

           Important

           Not all protocols have support for guarding against forwarding loops, and even for those that do,
           forwarding loops can be extremely detrimental to network performance.

           Note

           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.

           Tip

           Use the request/reply pattern, which includes automatic retries by the requester, if reliable
           delivery is needed.

RETURN VALUES

       This function continues running, and only returns an appropriate error when one occurs, or if one of the
       sockets is closed.

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.

SEE ALSO

       nng_options(5), nng_socket(5), nng(7)

                                                   2025-02-02                                      NNG_DEVICE(3)