= nng_pair(7) // // Copyright 2018 Staysail Systems, Inc. // Copyright 2018 Capitar IT Group BV // // 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 ---- .Version 1 [source,c] ---- #include ---- == DESCRIPTION (((protocol, _pair_))) The ((_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 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. 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 xref:nng_device.3.adoc[`nng_device()`]. 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 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. 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. 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`)):: (`bool`, 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. xref:nng_options.5.adoc#NNG_OPT_MAXTTL[`NNG_OPT_MAXTTL`]:: (`int`, version 1 only). Maximum time-to-live. === 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)]