diff options
| -rw-r--r-- | docs/man/nng_pair.7.adoc | 23 |
1 files changed, 15 insertions, 8 deletions
diff --git a/docs/man/nng_pair.7.adoc b/docs/man/nng_pair.7.adoc index aeb20407..dff13e8e 100644 --- a/docs/man/nng_pair.7.adoc +++ b/docs/man/nng_pair.7.adoc @@ -1,6 +1,6 @@ = nng_pair(7) // -// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// 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 @@ -33,10 +33,6 @@ nng_pair - pair protocol 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. @@ -44,7 +40,7 @@ The xref:nng_pair_open.3.adoc[`nng_pair_open()`] functions create a _pair_ socke 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 +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 @@ -69,13 +65,18 @@ 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 +CAUTION: Polyamorous mode was provided as an experiment, and that experiment +is deemed to have failed. +Thus use of this mode is discouraged. +In particular, the design cannot function over +xref:nng_device.3.adoc[device] proxies. +Consequently, this mode may be removed in a future release. + 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. @@ -91,6 +92,9 @@ 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: This capability _only_ works with directly connected peers. +It is not possible to use polyamorous mode in the presence of 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 @@ -106,6 +110,9 @@ The following protocol-specific options are available. The value is read-write, and takes an integer Boolean value. The default false value (0) indicates that legacy monogamous mode should be used. +NOTE: This option, and the associated capability are considered failed experiments. +Thus, use of it is discouraged, and it may be removed in a future release. + xref:nng_options.5.adoc#NNG_OPT_MAXTTL[`NNG_OPT_MAXTTL`]:: (`int`, version 1 only). Maximum time-to-live. |