diff options
Diffstat (limited to 'docs/nng_req.adoc')
| -rw-r--r-- | docs/nng_req.adoc | 136 |
1 files changed, 0 insertions, 136 deletions
diff --git a/docs/nng_req.adoc b/docs/nng_req.adoc deleted file mode 100644 index 550c90c4..00000000 --- a/docs/nng_req.adoc +++ /dev/null @@ -1,136 +0,0 @@ -= nng_req(7) -// -// Copyright 2018 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> - -int nng_req0_open(nng_socket *s); ----------- - -== DESCRIPTION - -The _nng_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.) - -The requester generally only has one outstanding request at a time unless -in "raw" mode (via `NNG_OPT_RAW`), and it will generally attempt to spread -work requests to different peer repliers. - -TIP: This property, when combined with a <<nng_device#,device>> can -help provide a degree of load-balancing. - -The _nng_req_ protocol is the requester side, and the -<<nng_rep#,nng_rep(7)>> protocol is the replier side. - -=== Socket Operations - -The `nng_req0_open()` call creates 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.) - -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. - -Attempts to receive on a socket with no outstanding requests will result -in `NNG_ESTATE`. - -Raw mode sockets (set with `NNG_OPT_RAW`) ignore all these restrictions. - -=== 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 options are available. - -`NNG_OPT_REQ_RESENDTIME`:: - - This read/write option is a duration (32-bit unsigned integer) representing - a relative number of milliseconds. - 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.) - -`NNG_OPT_MAXTTL`:: - - Maximum time-to-live. This option is an integer value - between 0 and 255, - inclusive, and is the maximum number of "hops" that a message may - pass through until it is discarded. The default value is 8. A value - of 0 may be used to disable the loop protection, allowing an infinite - number of hops. - -=== Protocol Headers - -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 preceeding 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 -<<nng_device#,nng_device(3)>>), 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 requestor, 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 - -<<nng_device(3)#,nng_device(3)>>, -<<nng#,nng(7)>>, -<<nng_rep#,nng_rep(7)>> |