Manual page updates for v1.8.0

1 files changed, 241 insertions, 0 deletions

diff --git a/man/v1.8.0/nng_req.7.html b/man/v1.8.0/nng_req.7.html
new file mode 100644
index 00000000..5b70582b
--- /dev/null
+++ b/man/v1.8.0/nng_req.7.html
@@ -0,0 +1,241 @@
+---
+version: v1.8.0
+layout: manpage_v2
+title: nng_req(7)
+---
+<h1>nng_req(7)</h1>
+<div class="sect1">
+<h2 id="_name">NAME</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>nng_req - request protocol</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_synopsis">SYNOPSIS</h2>
+<div class="sectionbody">
+<div class="listingblock">
+<div class="content">
+<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf">&lt;nng/protocol/reqrep0/req.h&gt;</span></code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_description">DESCRIPTION</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>
+The <em>req</em> protocol is one half of a request/reply pattern.
+In this pattern, a requester sends a message to one replier, who
+is expected to reply.
+The request is resent if no reply arrives,
+until a reply is received or the request times out.</p>
+</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+This protocol is useful in setting up RPC-like services.
+It is also "reliable", in that a the requester will keep retrying until
+a reply is received.
+</td>
+</tr>
+</table>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+Because requests are resent, it is important that they be idempotent
+to ensure predictable and repeatable behavior even in the face of duplicated
+requests, which can occur (for example if a reply message is lost for
+some reason.)
+</td>
+</tr>
+</table>
+</div>
+<div class="paragraph">
+<p>
+The requester generally only has one outstanding request at a time unless
+in raw mode (via
+<a href="nng_options.5.html#NNG_OPT_RAW"><code>NNG_OPT_RAW</code></a>),
+and it will generally attempt to spread work requests to different peer repliers.</p>
+</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+This property, when combined with <a href="nng_device.3.html"><code>nng_device()</code></a>
+can help provide a degree of load-balancing.
+</td>
+</tr>
+</table>
+</div>
+<div class="paragraph">
+<p>The <em>req</em> protocol is the requester side, and the
+<a href="nng_rep.7.html"><em>rep</em></a> protocol is the replier side.</p>
+</div>
+<div class="sect2">
+<h3 id="_socket_operations">Socket Operations</h3>
+<div class="paragraph">
+<p>The <a href="nng_req_open.3.html"><code>nng_req0_open()</code></a> functions create a requester socket.
+This socket may be used to send messages (requests), and then to receive replies.</p>
+</div>
+<div class="paragraph">
+<p>Generally a reply can only be received after sending a request.
+(Attempts to receive a message will result in <code>NNG_ESTATE</code> if there is no
+outstanding request.)</p>
+</div>
+<div class="paragraph">
+<p>Furthermore, only a single receive operation may be pending at a time.
+Attempts to post more receive operations concurrently will result in
+<code>NNG_ESTATE</code>.</p>
+</div>
+<div class="paragraph">
+<p>Requests may be canceled by sending a different request.
+This will cause the requester to discard any reply from the earlier request,
+but it will not stop a replier
+from processing a request it has already received or terminate a request
+that has already been placed on the wire.</p>
+</div>
+<div class="paragraph">
+<p><a href="nng.7.html#raw_mode">Raw</a> mode sockets ignore all these restrictions.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_context_operations">Context Operations</h3>
+<div class="paragraph">
+<p>This protocol supports the creation of <a href="nng_ctx.5.html">contexts</a> for concurrent
+use cases using <a href="nng_ctx_open.3.html"><code>nng_ctx_open()</code></a>.</p>
+</div>
+<div class="paragraph">
+<p>The <code>NNG_OPT_REQ_RESENDTIME</code> value may be configured differently
+on contexts created this way.</p>
+</div>
+<div class="paragraph">
+<p>Each context may have at most one outstanding request, and operates
+independently from the others.</p>
+</div>
+<div class="paragraph">
+<p>The restrictions for order of operations with sockets apply equally
+well for contexts, except that each context will be treated as if it were
+a separate socket.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_protocol_versions">Protocol Versions</h3>
+<div class="paragraph">
+<p>Only version 0 of this protocol is supported.
+(At the time of writing, no other versions of this protocol have been defined.)</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_protocol_options">Protocol Options</h3>
+<div class="paragraph">
+<p>The following protocol-specific option is available.</p>
+</div>
+<div class="dlist">
+<dl>
+<dt class="hdlist1"><code>NNG_OPT_REQ_RESENDTIME</code></dt>
+<dd>
+<p>(<a href="nng_duration.5.html"><code>nng_duration</code></a>)
+When a new request is started, a timer of this duration is also started.
+If no reply is received before this timer expires, then the request will
+be resent.</p>
+<div class="paragraph">
+<p>(Requests are also automatically resent if the peer to whom
+the original request was sent disconnects, or if a peer becomes available
+while the requester is waiting for an available peer.)</p>
+</div>
+<div class="paragraph">
+<p>Resending may be deferred up to the value of the <code>NNG_OPT_RESENDTICK</code> parameter.</p>
+</div>
+</dd>
+<dt class="hdlist1"><code>NNG_OPT_REQ_RESENDTICK</code></dt>
+<dd>
+<p>(<a href="nng_duration.5.html"><code>nng_duration</code></a>)
+This is the granularity of the clock that is used to check for resending.
+The default is a second.  Setting this to a higher rate will allow for
+more timely resending to occur, but may incur significant additional
+overhead when the socket has many outstanding requests (contexts).</p>
+<div class="paragraph">
+<p>When there are no requests outstanding that have a resend set, then
+the clock does not tick at all.</p>
+</div>
+<div class="paragraph">
+<p>This option is shared for all contexts on a socket, and is only available for the socket itself.</p>
+</div>
+</dd>
+</dl>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_protocol_headers">Protocol Headers</h3>
+<div class="paragraph">
+<p>
+This protocol uses a <em>backtrace</em> in the header.
+This form uses a stack of 32-bit big-endian identifiers.
+There <strong>must</strong> be at least one identifier, the <em>request ID</em>, which will be the
+last element in the array, and <strong>must</strong> have the most significant bit set.</p>
+</div>
+<div class="paragraph">
+<p>There may be additional <em>peer ID</em>s preceding the request ID.
+These will be distinguishable from the request ID by having their most
+significant bit clear.</p>
+</div>
+<div class="paragraph">
+<p>When a request message is received by a forwarding node (see
+<a href="nng_device.3.html"><code>nng_device()</code></a>), the forwarding node prepends a
+32-bit peer ID (which <strong>must</strong> have the most significant bit clear),
+which is the forwarder&#8217;s way of identifying the directly connected
+peer from which it received the message.
+(This peer ID, except for the
+most significant bit, has meaning only to the forwarding node itself.)</p>
+</div>
+<div class="paragraph">
+<p>It may help to think of prepending a peer ID as pushing a peer ID onto the
+front of the stack of headers for the message.
+(It will use the peer ID
+it popped from the front to determine the next intermediate destination
+for the reply.)</p>
+</div>
+<div class="paragraph">
+<p>When a reply message is created, it is created using the same headers
+that the request contained.</p>
+</div>
+<div class="paragraph">
+<p>A forwarding node can pop the peer ID it originally pushed on the
+message, stripping it from the front of the message as it does so.</p>
+</div>
+<div class="paragraph">
+<p>When the reply finally arrives back at the initiating requester, it
+should have only a single element in the message, which will be the
+request ID it originally used for the request.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_see_also">SEE ALSO</h2>
+<div class="sectionbody">
+<div class="paragraph text-left">
+<p><a href="nng_ctx_open.3.html">nng_ctx_open(3)</a>,
+<a href="nng_device.3.html">nng_device(3)</a>,
+<a href="nng_req_open.3.html">nng_req_open(3)</a>,
+<a href="nng_ctx.5.html">nng_ctx(5)</a>,
+<a href="nng.7.html">nng(7)</a>,
+<a href="nng_rep.7.html">nng_rep(7)</a></p>
+</div>
+</div>
+</div>