1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
= nng_pair(7)
//
// Copyright 2018 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>
int nng_pair0_open(nng_socket *s);
----------
.Version 1
[source,c]
----------
#include <nng/protocol/pair1/pair.h>
int nng_pair1_open(nng_socket *s);
----------
== DESCRIPTION
The _nng_pair_ protocol implements a peer-to-peer pattern, where
relationships between peers are one-to-one.
Version 1 of this protocol supports an optional _polyamorous_ mode where a
peer can maintain multiple partnerships. Using this mode requires
some additional sophistication in the application.
=== Socket Operations
The `nng_pair_open()` call creates 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 <<nng_device#,nng_device(3)>>) or raw mode sockets where
messages may be discarded. Applications that require reliable delivery
semantics should consider using <<nng_req#,nng_req(7)>> sockets, or
implement their own acknowledgement layer on top of pair sockets.
In order to avoid head-of-line blocking conditions, _polyamorous_ mode pair
sockets (version 1 only) discard messages if they are unable to deliver them
to a peer.
=== 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 <<nng_device#,nng_device(3)>>. It also offers _polyamorous_
mode for forming multiple partnerships on a single socket.
NOTE: Version 1 of this protocol is considered experimental at this time.
=== Polyamorous Mode
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.
In _polyamorous_ mode, which is only available with version 1, a socket can
support many one-to-one connections. In this mode, the application must
choose the remote peer to receive an ougoing message by setting the value
of the pipe ID on the outgoing message using
the <<nng_msg_set_pipe#,nng_msg_set_pipe(3)>> function.
Most often the value of the outgoing pipe ID will be obtained from an incoming
message using the <<nng_msg_get_pipe#,nng_msg_get_pipe(3)>> function,
such as when replying to an incoming message.
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.
`NNG_OPT_PAIR1_POLY`::
(Version 1 only). This option enables the use of _polyamorous_ mode.
The value is read-write, and takes an integer boolean value. The default
false value (0) indicates that legacy monogamous mode should be used.
`NNG_OPT_MAXTTL`::
(Version 1 only). Maximum time-to-live. This option is an integer value
between 0 and 255,
inclusive, and is the maximum number of "hops" that a message may
pass through until it is discarded. The default value is 8. A value
of 0 may be used to disable the loop protection, allowing an infinite
number of hops.
+
TIP: Each node along a forwarding path may have it's own value for the
maximum time-to-live, and performs its own checks before forwarding a message.
Therefore it is helpful if all nodes in the topology use the same value for
this option.
=== 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 conjuction 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.
== SEE ALSO
<<nng#,nng(7)>>
|
