|This documentation is for the TIP (development tree) of NNG and may represent unreleased changes or functionality that is experimental, and is subject to change before release. The latest released version is v1.3.2. See the documentation for v1.3.2 for the most up-to-date information.|
nng_pair - pair protocol
(protocol, pair) The pair protocol implements a peer-to-peer pattern, where relationships between peers are one-to-one.
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.
Even though this mode may appear to be reliable, because back-pressure
prevents discarding messages most of the time, there are topologies involving
Version 0 is the legacy version of this protocol. It lacks any header information, and is suitable when building simple one-to-one topologies.
|Use version 0 if you need to communicate with other implementations, including the legacy nanomsg library or mangos.|
Version 1 of the protocol offers improved protection against loops when
|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
|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
nng_pipe to use for the outgoing message with
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
such as when replying to an incoming message.
|Directed send only works with directly connected peers. It will not function across 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.
The following protocol-specific options are available.
int, version 1 only). Maximum time-to-live.
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
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
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.