From e8d6c2bf692dbcb4c503caa676314a6a626a8a68 Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Mon, 14 Oct 2024 18:08:13 -0700
Subject: Converted protocols to mdbook.

Started an introductory section too.
---
 docs/man/nng_req.7.adoc | 171 ------------------------------------------------
 1 file changed, 171 deletions(-)
 delete mode 100644 docs/man/nng_req.7.adoc

(limited to 'docs/man/nng_req.7.adoc')

diff --git a/docs/man/nng_req.7.adoc b/docs/man/nng_req.7.adoc
deleted file mode 100644
index 1d958562..00000000
--- a/docs/man/nng_req.7.adoc
+++ /dev/null
@@ -1,171 +0,0 @@
-= nng_req(7)
-//
-// Copyright 2023 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_req - request protocol
-
-== SYNOPSIS
-
-[source,c]
-----
-#include <nng/protocol/reqrep0/req.h>
-----
-
-== DESCRIPTION
-
-(((protocol, _req_)))
-The ((_req_ 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.
-
-TIP: 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.
-
-NOTE: 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.)
-
-(((load-balancing)))
-The requester generally only has one outstanding request at a time unless
-in raw mode (via
-xref:nng_options.5.adoc#NNG_OPT_RAW[`NNG_OPT_RAW`]),
-and it will generally attempt to spread work requests to different peer repliers.
-
-TIP: This property, when combined with xref:nng_device.3.adoc[`nng_device()`]
-can help provide a degree of load-balancing.
-
-The _req_ protocol is the requester side, and the
-xref:nng_rep.7.adoc[_rep_] protocol is the replier side.
-
-=== Socket Operations
-
-The xref:nng_req_open.3.adoc[`nng_req0_open()`] functions create a requester socket.
-This socket may be used to send messages (requests), and then to receive replies.
-
-Generally a reply can only be received after sending a request.
-(Attempts to receive a message will result in `NNG_ESTATE` if there is no
-outstanding request.)
-
-Furthermore, only a single receive operation may be pending at a time.
-Attempts to post more receive operations concurrently will result in
-`NNG_ESTATE`.
-
-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.
-
-xref:nng.7.adoc#raw_mode[Raw] mode sockets ignore all these restrictions.
-
-=== Context Operations
-
-This protocol supports the creation of xref:nng_ctx.5.adoc[contexts] for concurrent
-use cases using xref:nng_ctx_open.3.adoc[`nng_ctx_open()`].
-
-The `NNG_OPT_REQ_RESENDTIME` value may be configured differently
-on contexts created this way.
-
-Each context may have at most one outstanding request, and operates
-independently from the others.
-
-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.
-
-=== Protocol Versions
-
-Only version 0 of this protocol is supported.
-(At the time of writing, no other versions of this protocol have been defined.)
-
-=== Protocol Options
-
-The following protocol-specific option is available.
-
-((`NNG_OPT_REQ_RESENDTIME`))::
-
-   (xref:nng_duration.5.adoc[`nng_duration`])
-   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.
-+
-(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.)
-+
-Resending may be deferred up to the value of the `NNG_OPT_RESENDTICK` parameter.
-
-((`NNG_OPT_REQ_RESENDTICK`))::
-
-   (xref:nng_duration.5.adoc[`nng_duration`])
-   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).
-+
-When there are no requests outstanding that have a resend set, then
-the clock does not tick at all.
-+
-This option is shared for all contexts on a socket, and is only available for the socket itself.
-
-
-=== Protocol Headers
-
-(((backtrace)))
-This protocol uses a _backtrace_ in the header.
-This form uses a stack of 32-bit big-endian identifiers.
-There *must* be at least one identifier, the __request ID__, which will be the
-last element in the array, and *must* have the most significant bit set.
-
-There may be additional __peer ID__s preceding the request ID.
-These will be distinguishable from the request ID by having their most
-significant bit clear.
-
-When a request message is received by a forwarding node (see
-xref:nng_device.3.adoc[`nng_device()`]), the forwarding node prepends a
-32-bit peer ID (which *must* have the most significant bit clear),
-which is the forwarder'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.)
-
-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.)
-
-When a reply message is created, it is created using the same headers
-that the request contained.
-
-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.
-
-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.
-
-// TODO: Insert reference to RFC.
-
-== SEE ALSO
-
-[.text-left]
-xref:nng_ctx_open.3.adoc[nng_ctx_open(3)],
-xref:nng_device.3.adoc[nng_device(3)],
-xref:nng_req_open.3.adoc[nng_req_open(3)],
-xref:nng_ctx.5.adoc[nng_ctx(5)],
-xref:nng.7.adoc[nng(7)],
-xref:nng_rep.7.adoc[nng_rep(7)]
-- 
cgit v1.2.3-70-g09d2

