From 454c4a6d2af3becb703005d1805e001d3d0c76f1 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 30 Mar 2024 21:13:45 -0700 Subject: converted nng_device --- docs/man/nng_device.3.adoc | 122 ---------------------------------- docs/reference/src/SUMMARY.md | 1 + docs/reference/src/refs.md | 1 + docs/reference/src/sock/nng_device.md | 113 +++++++++++++++++++++++++++++++ 4 files changed, 115 insertions(+), 122 deletions(-) delete mode 100644 docs/man/nng_device.3.adoc create mode 100644 docs/reference/src/sock/nng_device.md 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. -// 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); - -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)] diff --git a/docs/reference/src/SUMMARY.md b/docs/reference/src/SUMMARY.md index fe9913f2..2315b515 100644 --- a/docs/reference/src/SUMMARY.md +++ b/docs/reference/src/SUMMARY.md @@ -53,6 +53,7 @@ - [nng_bus_open](sock/nng_bus_open.md) - [nng_close](sock/nng_close.md) + - [nng_device](sock/nng_device.md) - [nng_pub_open](sock/nng_pub_open.md) - [Contexts](ctx/index.md) diff --git a/docs/reference/src/refs.md b/docs/reference/src/refs.md index 44dd69a3..97bea94a 100644 --- a/docs/reference/src/refs.md +++ b/docs/reference/src/refs.md @@ -48,6 +48,7 @@ [nng_surveyor_open]: ../sock/nng_surveyor_open.md [nng_sub_open]: ../sock/nng_sub_open.md [nng_close]: ../sock/nng_close.md +[nng_device]: ../sock/nng_device.md diff --git a/docs/reference/src/sock/nng_device.md b/docs/reference/src/sock/nng_device.md new file mode 100644 index 00000000..1c59314a --- /dev/null +++ b/docs/reference/src/sock/nng_device.md @@ -0,0 +1,113 @@ +# nng_device + +## NAME + +nng_device - message forwarding device + +## SYNOPSIS + +```c +#include + +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][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 {{i:horizontal scalability}}, +reliability, and isolation. + +Only [raw mode][raw] 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()`][nng_req_open]. + +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 {{i:`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_][pair] or [_BUS_][bus]). +In this case the device acts as a {{i:reflector}} or {{i: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 {{i: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_][pub] socket, then _s2_ must +be a [_SUB_][sub] socket. +Or, if _s1_ is a [_BUS_][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 {{i: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 {{i: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`][NNG_OPT_MAXTTL] option. + +> [!NOTE] +> 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 {{i:best-effort}} delivery +> mode only. +> If a message is received from one socket that cannot be accepted by the +> other (due to {{i:back-pressure}} 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 + +[Sockets][socket], +[Raw mode][raw] + +{{#include ../refs.md}} -- cgit v1.2.3-70-g09d2