From e8d6c2bf692dbcb4c503caa676314a6a626a8a68 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore 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. -// 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_req - request protocol - -== SYNOPSIS - -[source,c] ----- -#include ----- - -== 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