diff options
Diffstat (limited to 'docs/man')
| -rw-r--r-- | docs/man/nng_device.3.adoc | 122 |
1 files changed, 0 insertions, 122 deletions
diff --git a/docs/man/nng_device.3.adoc b/docs/man/nng_device.3.adoc deleted file mode 100644 index 7151239f..00000000 --- a/docs/man/nng_device.3.adoc +++ /dev/null @@ -1,122 +0,0 @@ -= nng_device(3) -// -// Copyright 2021 Staysail Systems, Inc. <info@staysail.tech> -// Copyright 2018 Capitar IT Group BV <info@capitar.com> -// -// 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 <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 -xref:nng_socket.5.adoc[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 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. -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 -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 -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. - -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 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)] |