Advise on the impending demise of polyamorous mode.

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.