oxmox
17f68cf8fe
git-subtree-dir: external/nng git-subtree-split: 169221da8d53b2ca4fda76f894bee8505887a7c6
135 lines
4.5 KiB
Text
135 lines
4.5 KiB
Text
= 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)]
|