diff options
Diffstat (limited to 'docs/man/nng_pair.7.adoc')
| -rw-r--r-- | docs/man/nng_pair.7.adoc | 135 |
1 files changed, 0 insertions, 135 deletions
diff --git a/docs/man/nng_pair.7.adoc b/docs/man/nng_pair.7.adoc deleted file mode 100644 index 9a035823..00000000 --- a/docs/man/nng_pair.7.adoc +++ /dev/null @@ -1,135 +0,0 @@ -= nng_pair(7) -// -// Copyright 2020 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_pair - pair protocol - -== SYNOPSIS - -.Version 0 -[source,c] ----- -#include <nng/protocol/pair0/pair.h> ----- - -.Version 1 -[source,c] ----- -#include <nng/protocol/pair1/pair.h> ----- - -== DESCRIPTION - -(((protocol, _pair_))) -The ((_pair_ protocol)) implements a peer-to-peer pattern, where -relationships between peers are one-to-one. - -=== Socket Operations - -The xref:nng_pair_open.3.adoc[`nng_pair_open()`] functions create a _pair_ socket. - -Normally, this pattern will block when attempting to send a message if -no peer is able to receive the message. - -NOTE: Even though this mode may appear to be reliable, because back-pressure -prevents discarding messages most of the time, there are topologies involving -_devices_ (see xref:nng_device.3.adoc[`nng_device()`]) or raw mode sockets -(see xref:nng_options.5.adoc#NNG_OPT_RAW[`NNG_OPT_RAW`]) where -messages may be discarded. -Applications that require reliable delivery semantics should consider using -xref:nng_req.7.adoc[_req_] sockets, or -implement their own acknowledgment layer on top of _pair_ sockets. - -=== Protocol Versions - -Version 0 is the legacy version of this protocol. -It lacks any header -information, and is suitable when building simple one-to-one topologies. - -TIP: Use version 0 if you need to communicate with other implementations, -including the legacy https://github.com/nanomsg/nanomsg[nanomsg] library or -https://github.com/go-mangos/mangos[mangos]. - -Version 1 of the protocol offers improved protection against loops when -used with xref:nng_device.3.adoc[`nng_device()`]. - -=== Polyamorous Mode - -WARNING: Polyamorous mode is deprecated, and support for it will likely -be removed in a future release. -Applications are strongly discouraged from making further use of it. - -Normally pair sockets are for one-to-one communication, and a given peer -will reject new connections if it already has an active connection to another -peer. - -((_Polyamorous_ mode)) changes this, to allow a socket to communicate with -multiple directly-connected peers. -This mode is enabled by opening a socket with the -xref:nng_pair_open.3.adoc[`nng_pair1_open_poly()`] -function - -NOTE: Polyamorous mode is only available when using pair version 1. - -In polyamorous mode a socket can support many one-to-one connections. -In this mode, the application must -choose the remote peer to receive an outgoing message by setting the -xref:nng_pipe.5.adoc[`nng_pipe`] to use for the outgoing message with -the xref:nng_msg_set_pipe.3.adoc[`nng_msg_set_pipe()`] function. - -If no remote peer is specified by the sender, then the protocol will select -any available connected peer. - -Most often the value of the outgoing pipe will be obtained from an incoming -message using the xref:nng_msg_get_pipe.3.adoc[`nng_msg_get_pipe()`] function, -such as when replying to an incoming message. - -NOTE: Directed send _only_ works with directly connected peers. -It will not function across xref:nng_device.3.adoc[device] proxies. - -In order to prevent head-of-line blocking, if the peer on the given pipe -is not able to receive (or the pipe is no longer available, such as if the -peer has disconnected), then the message will be discarded with no notification -to the sender. - -=== Protocol Options - -The following protocol-specific options are available. - -xref:nng_options.5.adoc#NNG_OPT_MAXTTL[`NNG_OPT_MAXTTL`]:: - - (`int`, version 1 only). Maximum time-to-live. - -((`NNG_OPT_PAIR1_POLY`)):: - - (`bool`, version 1 only) This option is no longer supported. - Formerly it was used to configure _polyamorous_ mode, but that mode - is now established by using the `nng_pair1_open_poly()` function. - -=== Protocol Headers - -Version 0 of the pair protocol has no protocol-specific headers. - -Version 1 of the pair protocol uses a single 32-bit unsigned value. The -low-order (big-endian) byte of this value contains a "hop" count, and is -used in conjunction with the -xref:nng_options.5.adoc#NNG_OPT_MAXTTL[`NNG_OPT_MAXTTL`] option to guard against -device forwarding loops. -This value is initialized to 1, and incremented each time the message is -received by a new node. - -== SEE ALSO - -[.text-left] -xref:nng_pair_open.3.adoc[nng_pair_open(3)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng.7.adoc[nng(7)] |