diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/nng_rep.adoc | 111 | ||||
| -rw-r--r-- | docs/nng_req.adoc | 139 | ||||
| -rw-r--r-- | docs/nng_surveyor.adoc | 2 |
3 files changed, 251 insertions, 1 deletions
diff --git a/docs/nng_rep.adoc b/docs/nng_rep.adoc new file mode 100644 index 00000000..e6cfa73e --- /dev/null +++ b/docs/nng_rep.adoc @@ -0,0 +1,111 @@ +nng_rep(7) +========== +:doctype: manpage +:manmanual: nng +:mansource: nng +:icons: font +:source-highlighter: pygments +:copyright: Copyright 2017 Garrett D'Amore <garrett@damore.org> \ + Copyright 2017 Capitar IT Group BV <info@capitar.com> \ + This software 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_rep - reply protocol + +SYNOPSIS +-------- + +[source,c] +---------- +#include <nng/protocol/reqrep0/rep.h> + +int nng_rep0_open(nng_socket *s); +---------- + +DESCRIPTION +----------- + +The _nng_rep_ 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. + +The _nng_rep_ protocol is the replier side, and the +<<nng_req.adoc#,nng_req(7)>> protocol is the requester side. + +Socket Operations +~~~~~~~~~~~~~~~~~ + +The `nng_rep0_open()` call creates a requester socket. This socket +may be used to receive messages (requests), and then to send replies. Generally +a reply can only be sent after receiving a request. (Attempts to receive +a message will result in `NNG_ESTATE` if there is no outstanding request.) + +Attempts to send 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_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 +~~~~~~~~~~~~~~~~ + +The _nng_rep_ protocol uses a _backtrace_ in the header. This +form uses an array of 32-bit big-endian identifiers, where the first +element in the array +identifies the local peer identifier to which the message will next be sent. +This is a hop-by-hop header where each element in a path adds routing +information to the end when sending a request, and when replying removes +elements to obtain the next hop information. The request ID is at the +end of this header and is inserted into the header as its first element +by the originating surveyor. (Request IDs are distinguished from hops by +having their high order bit set to one. They are generated automatically +and randomly when a request is first issued.) + +// TODO: Insert reference to RFC. + + +AUTHORS +------- +link:mailto:garrett@damore.org[Garrett D'Amore] + +SEE ALSO +-------- +<<nng.adoc#,nng(7)>> +<<nng_req.adoc#,nng_req(7)>> + +COPYRIGHT +--------- + +Copyright 2017 mailto:garrett@damore.org[Garrett D'Amore] + +Copyright 2017 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/LICENSE.txt[MIT License]. diff --git a/docs/nng_req.adoc b/docs/nng_req.adoc new file mode 100644 index 00000000..90a9ccf4 --- /dev/null +++ b/docs/nng_req.adoc @@ -0,0 +1,139 @@ +nng_req(7) +========== +:doctype: manpage +:manmanual: nng +:mansource: nng +:icons: font +:source-highlighter: pygments +:copyright: Copyright 2017 Garrett D'Amore <garrett@damore.org> \ + Copyright 2017 Capitar IT Group BV <info@capitar.com> \ + This software 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.adoc#,device>> can +help provide a degree of load-balancing. + +The _nng_req_ protocol is the requester side, and the +<<nng_rep.adoc#,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 +~~~~~~~~~~~~~~~~ + +The _nng_req_ protocol uses a _backtrace_ in the header. This +form uses an array of 32-bit big-endian identifiers, where the first +element in the array +identifies the local peer identifier to which the message will next be sent. +This is a hop-by-hop header where each element in a path adds routing +information to the end when sending a request, and when replying removes +elements to obtain the next hop information. The request ID is at the +end of this header and is inserted into the header as its first element +by the originating surveyor. (Request IDs are distinguished from hops by +having their high order bit set to one. They are generated automatically +and randomly when a request is first issued.) + +// TODO: Insert reference to RFC. + + +AUTHORS +------- +link:mailto:garrett@damore.org[Garrett D'Amore] + +SEE ALSO +-------- +<<nng.adoc#,nng(7)>> +<<nng_rep.adoc#,nng_rep(7)>> + +COPYRIGHT +--------- + +Copyright 2017 mailto:garrett@damore.org[Garrett D'Amore] + +Copyright 2017 mailto:info@capitar.com[Capitar IT Group BV] + +This document is supplied under the terms of the +https://opensource.org/licenses/LICENSE.txt[MIT License]. diff --git a/docs/nng_surveyor.adoc b/docs/nng_surveyor.adoc index c995344e..5eead82a 100644 --- a/docs/nng_surveyor.adoc +++ b/docs/nng_surveyor.adoc @@ -82,7 +82,7 @@ The following protocol-specific options are available. When a new survey is started, a timer of this duration is also started. Any responses arriving this time will be discarded. Attempts to receive after the timer expires with no other surveys started will result in - `NNG_ESTATE`. Attempts to receive when this timer will result include + `NNG_ESTATE`. Attempts to receive when this timer expires will result in `NNG_ETIMEDOUT`. `NNG_OPT_MAXTTL`:: |