1= nng_pair(7)
2//
3// Copyright 2020 Staysail Systems, Inc. <info@staysail.tech>
4// Copyright 2018 Capitar IT Group BV <info@capitar.com>
5//
6// This document is supplied under the terms of the MIT License, a
7// copy of which should be located in the distribution where this
8// file was obtained (LICENSE.txt).  A copy of the license may also be
9// found online at https://opensource.org/licenses/MIT.
10//
11
12== NAME
13
14nng_pair - pair protocol
15
16== SYNOPSIS
17
18.Version 0
19[source,c]
20----
21#include <nng/protocol/pair0/pair.h>
22----
23
24.Version 1
25[source,c]
26----
27#include <nng/protocol/pair1/pair.h>
28----
29
30== DESCRIPTION
31
32(((protocol, _pair_)))
33The ((_pair_ protocol)) implements a peer-to-peer pattern, where
34relationships between peers are one-to-one.
35
36=== Socket Operations
37
38The xref:nng_pair_open.3.adoc[`nng_pair_open()`] functions create a _pair_ socket.
39
40Normally, this pattern will block when attempting to send a message if
41no peer is able to receive the message.
42
43NOTE: Even though this mode may appear to be reliable, because back-pressure
44prevents discarding messages most of the time, there are topologies involving
45_devices_ (see xref:nng_device.3.adoc[`nng_device()`]) or raw mode sockets
46(see xref:nng_options.5.adoc#NNG_OPT_RAW[`NNG_OPT_RAW`]) where
47messages may be discarded.
48Applications that require reliable delivery semantics should consider using
49xref:nng_req.7.adoc[_req_] sockets, or
50implement their own acknowledgment layer on top of _pair_ sockets.
51
52=== Protocol Versions
53
54Version 0 is the legacy version of this protocol.
55It lacks any header
56information, and is suitable when building simple one-to-one topologies.
57
58TIP: Use version 0 if you need to communicate with other implementations,
59including the legacy https://github.com/nanomsg/nanomsg[nanomsg] library or
60https://github.com/go-mangos/mangos[mangos].
61
62Version 1 of the protocol offers improved protection against loops when
63used with xref:nng_device.3.adoc[`nng_device()`].
64
65=== Polyamorous Mode
66
67WARNING: Polyamorous mode is deprecated, and support for it will likely
68be removed in a future release.
69Applications are strongly discouraged from making further use of it.
70
71Normally pair sockets are for one-to-one communication, and a given peer
72will reject new connections if it already has an active connection to another
73peer.
74
75((_Polyamorous_ mode)) changes this, to allow a socket to communicate with
76multiple directly-connected peers.
77This mode is enabled by opening a socket with the
78xref:nng_pair_open.3.adoc[`nng_pair1_open_poly()`]
79function
80
81NOTE: Polyamorous mode is only available when using pair version 1.
82
83In polyamorous mode a socket can support many one-to-one connections.
84In this mode, the application must
85choose the remote peer to receive an outgoing message by setting the
86xref:nng_pipe.5.adoc[`nng_pipe`] to use for the outgoing message with
87the xref:nng_msg_set_pipe.3.adoc[`nng_msg_set_pipe()`] function.
88
89If no remote peer is specified by the sender, then the protocol will select
90any available connected peer.
91
92Most often the value of the outgoing pipe will be obtained from an incoming
93message using the xref:nng_msg_get_pipe.3.adoc[`nng_msg_get_pipe()`] function,
94such as when replying to an incoming message.
95
96NOTE: Directed send _only_ works with directly connected peers.
97It will not function across xref:nng_device.3.adoc[device] proxies.
98
99In order to prevent head-of-line blocking, if the peer on the given pipe
100is not able to receive (or the pipe is no longer available, such as if the
101peer has disconnected), then the message will be discarded with no notification
102to the sender.
103
104=== Protocol Options
105
106The following protocol-specific options are available.
107
108xref:nng_options.5.adoc#NNG_OPT_MAXTTL[`NNG_OPT_MAXTTL`]::
109
110   (`int`, version 1 only).  Maximum time-to-live.
111
112((`NNG_OPT_PAIR1_POLY`))::
113
114   (`bool`, version 1 only)  This option is no longer supported.
115   Formerly it was used to configure _polyamorous_ mode, but that mode
116   is now established by using the `nng_pair1_open_poly()` function.
117
118=== Protocol Headers
119
120Version 0 of the pair protocol has no protocol-specific headers.
121
122Version 1 of the pair protocol uses a single 32-bit unsigned value.  The
123low-order (big-endian) byte of this value contains a "hop" count, and is
124used in conjunction with the
125xref:nng_options.5.adoc#NNG_OPT_MAXTTL[`NNG_OPT_MAXTTL`] option to guard against
126device forwarding loops.
127This value is initialized to 1, and incremented each time the message is
128received by a new node.
129
130== SEE ALSO
131
132[.text-left]
133xref:nng_pair_open.3.adoc[nng_pair_open(3)],
134xref:nng_options.5.adoc[nng_options(5)],
135xref:nng.7.adoc[nng(7)]
136