122 lines
4.3 KiB
Text
122 lines
4.3 KiB
Text
= 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)]
|