= nng_device(3) // // Copyright 2018 Staysail Systems, Inc. // Copyright 2018 Capitar IT Group BV // // This document is supplied under the terms of the MIT License, a // copy of which should be located in the distribution where this // file was obtained (LICENSE.txt). A copy of the license may also be // found online at https://opensource.org/licenses/MIT. // == NAME nng_device - message forwarding device == SYNOPSIS [source, c] ---- #include int nng_device(nng_socket s1, nng_socket s2); ---- == DESCRIPTION The `nng_device()` function forwards messages received from one xref:nng_socket.5.adoc[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. Only xref:nng_options.5.adoc#NNG_OPT_RAW[raw] mode sockets may be used with this function. These can be created using `_raw` forms of the various socket constructors, such as xref:nng_req_open.3.adoc[`nng_req0_open_raw()`]. The `nng_device()` function does not return until one of the sockets is closed. === 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 xref:nng_pair.7.adoc[_pair_] or xref:nng_bus.7.adoc[_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 xref:nng_pub.7.adoc[_pub_] socket, then _s2_ must be a xref:nng_sub.7.adoc[_sub_] socket. Or, if _s1_ is a xref:nng_bus.7.adoc[_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. 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 xref:nng_options.5.adoc#NNG_OPT_MAXTTL[`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 [horizontal] `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 [.text-left] xref:nng_options.5.adoc[nng_options(5)], xref:nng_socket.5.adoc[nng_socket(5)], xref:nng.7.adoc[nng(7)]