diff options
Diffstat (limited to 'docs/man')
| -rw-r--r-- | docs/man/nng.7.adoc | 28 | ||||
| -rw-r--r-- | docs/man/nng_bus.7.adoc | 84 | ||||
| -rw-r--r-- | docs/man/nng_pair.7.adoc | 135 | ||||
| -rw-r--r-- | docs/man/nng_pub.7.adoc | 69 | ||||
| -rw-r--r-- | docs/man/nng_pull.7.adoc | 65 | ||||
| -rw-r--r-- | docs/man/nng_push.7.adoc | 80 | ||||
| -rw-r--r-- | docs/man/nng_rep.7.adoc | 86 | ||||
| -rw-r--r-- | docs/man/nng_req.7.adoc | 171 | ||||
| -rw-r--r-- | docs/man/nng_respondent.7.adoc | 91 | ||||
| -rw-r--r-- | docs/man/nng_sub.7.adoc | 99 | ||||
| -rw-r--r-- | docs/man/nng_surveyor.7.adoc | 149 |
11 files changed, 14 insertions, 1043 deletions
diff --git a/docs/man/nng.7.adoc b/docs/man/nng.7.adoc index c0e1a640..2c5d0d72 100644 --- a/docs/man/nng.7.adoc +++ b/docs/man/nng.7.adoc @@ -50,19 +50,19 @@ application developer to use the new-style API. _NNG_ is implemented in pure C; if you need bindings for other languages please check the http://nanomsg.org/[website]. -=== Protocols - -[horizontal] -xref:nng_bus.7.adoc[nng_bus(7)]:: Bus protocol -xref:nng_pair.7.adoc[nng_pair(7)]:: Pair protocol -xref:nng_pub.7.adoc[nng_pub(7)]:: Publisher side of publish/subscribe protocol -xref:nng_pull.7.adoc[nng_pull(7)]:: Pull side of pipeline protocol -xref:nng_push.7.adoc[nng_push(7)]:: Push side of pipeline protocol -xref:nng_sub.7.adoc[nng_sub(7)]:: Subscriber side of publish/subscribe protocol -xref:nng_rep.7.adoc[nng_rep(7)]:: Reply side of request/reply protocol -xref:nng_req.7.adoc[nng_req(7)]:: Request side of request/reply protocol -xref:nng_respondent.7.adoc[nng_respondent(7)]:: Respondent side of survey protocol -xref:nng_surveyor.7.adoc[nng_surveyor(7)]:: Surveyor side of survey protocol +// === Protocols + +// [horizontal] +// xref:nng_bus.7.adoc[nng_bus(7)]:: Bus protocol +// xref:nng_pair.7.adoc[nng_pair(7)]:: Pair protocol +// xref:nng_pub.7.adoc[nng_pub(7)]:: Publisher side of publish/subscribe protocol +// xref:nng_pull.7.adoc[nng_pull(7)]:: Pull side of pipeline protocol +// xref:nng_push.7.adoc[nng_push(7)]:: Push side of pipeline protocol +// xref:nng_sub.7.adoc[nng_sub(7)]:: Subscriber side of publish/subscribe protocol +// xref:nng_rep.7.adoc[nng_rep(7)]:: Reply side of request/reply protocol +// xref:nng_req.7.adoc[nng_req(7)]:: Request side of request/reply protocol +// xref:nng_respondent.7.adoc[nng_respondent(7)]:: Respondent side of survey protocol +// xref:nng_surveyor.7.adoc[nng_surveyor(7)]:: Surveyor side of survey protocol === Transports @@ -174,7 +174,7 @@ https://tools.ietf.org/html/rfc3986#section-6.2.2[RFC 3986 6.2.2]: slash (`/`) separators are removed from the path. Note that steps 4, 5, and 7 are not specified by RFC 3986, but performing -them is believed to improve both the usability and security of +them is believed to improve both the usability and security of applications, without violating RFC 3986 itself. TIP: Port numbers may be service names in some instances, but it is recommended diff --git a/docs/man/nng_bus.7.adoc b/docs/man/nng_bus.7.adoc deleted file mode 100644 index 67b3d974..00000000 --- a/docs/man/nng_bus.7.adoc +++ /dev/null @@ -1,84 +0,0 @@ -= nng_bus(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_bus - bus protocol - -== SYNOPSIS - -[source,c] ----- -#include <nng/protocol/bus0/bus.h> ----- - -== DESCRIPTION - -(((protocol, _bus_))) -The ((_bus_ protocol)) provides for building mesh networks where -every peer is connected to every other peer. -In this protocol, each message sent by a node is sent to every one of -its directly connected peers. - -TIP: Messages are only sent to directly connected peers. -This means that in the event that a peer is connected indirectly, it will not -receive messages. -When using this protocol to build mesh networks, it -is therefore important that a _fully-connected_ mesh network be constructed. - -All message delivery in this pattern is ((best-effort)), which means that -peers may not receive messages. -Furthermore, delivery may occur to some, -all, or none of the directly connected peers. -(Messages are not delivered when peer nodes are unable to receive.) -Hence, send operations will never block; instead if the -message cannot be delivered for any reason it is discarded. - -TIP: In order to minimize the likelihood of message loss, this protocol -should not be used for high throughput communications. -Furthermore, the more traffic _in aggregate_ that occurs across the topology, -the more likely that message loss is to occur. - -=== Socket Operations - -The xref:nng_bus_open.3.adoc[`nng_bus0_open()`] functions create a bus socket. -This socket may be used to send and receive messages. -Sending messages will attempt to deliver to each directly connected peer. - -=== 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 _bus_ protocol has no protocol-specific options. - -=== Protocol Headers - -When using a _bus_ socket in xref:nng.7.adoc#raw_mode[raw mode], received messages will -contain the incoming xref:nng_pipe.5.adoc[pipe] ID as the sole element in the header. -If a message containing such a header is sent using a raw _bus_ socket, then, -the message will be delivered to all connected pipes _except_ the one -identified in the header. -This behavior is intended for use with xref:nng_device.3.adoc[device] -configurations consisting of just a single socket. -Such configurations are useful in the creation of rebroadcasters, and this -capability prevents a message from being routed back to its source. -If no header is present, then a message is sent to all connected pipes. - -When using normal (cooked mode) _bus_ sockets, no message headers are present. - -== SEE ALSO - -[.text-left] -xref:nng_bus_open.3.adoc[nng_bus_open(3)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_pair.7.adoc b/docs/man/nng_pair.7.adoc deleted file mode 100644 index 9a035823..00000000 --- a/docs/man/nng_pair.7.adoc +++ /dev/null @@ -1,135 +0,0 @@ -= nng_pair(7) -// -// Copyright 2020 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_pair - pair protocol - -== SYNOPSIS - -.Version 0 -[source,c] ----- -#include <nng/protocol/pair0/pair.h> ----- - -.Version 1 -[source,c] ----- -#include <nng/protocol/pair1/pair.h> ----- - -== DESCRIPTION - -(((protocol, _pair_))) -The ((_pair_ protocol)) implements a peer-to-peer pattern, where -relationships between peers are one-to-one. - -=== Socket Operations - -The xref:nng_pair_open.3.adoc[`nng_pair_open()`] functions create a _pair_ socket. - -Normally, this pattern will block when attempting to send a message if -no peer is able to receive the message. - -NOTE: Even though this mode may appear to be reliable, because back-pressure -prevents discarding messages most of the time, there are topologies involving -_devices_ (see xref:nng_device.3.adoc[`nng_device()`]) or raw mode sockets -(see xref:nng_options.5.adoc#NNG_OPT_RAW[`NNG_OPT_RAW`]) where -messages may be discarded. -Applications that require reliable delivery semantics should consider using -xref:nng_req.7.adoc[_req_] sockets, or -implement their own acknowledgment layer on top of _pair_ sockets. - -=== Protocol Versions - -Version 0 is the legacy version of this protocol. -It lacks any header -information, and is suitable when building simple one-to-one topologies. - -TIP: Use version 0 if you need to communicate with other implementations, -including the legacy https://github.com/nanomsg/nanomsg[nanomsg] library or -https://github.com/go-mangos/mangos[mangos]. - -Version 1 of the protocol offers improved protection against loops when -used with xref:nng_device.3.adoc[`nng_device()`]. - -=== Polyamorous Mode - -WARNING: Polyamorous mode is deprecated, and support for it will likely -be removed in a future release. -Applications are strongly discouraged from making further use of it. - -Normally pair sockets are for one-to-one communication, and a given peer -will reject new connections if it already has an active connection to another -peer. - -((_Polyamorous_ mode)) changes this, to allow a socket to communicate with -multiple directly-connected peers. -This mode is enabled by opening a socket with the -xref:nng_pair_open.3.adoc[`nng_pair1_open_poly()`] -function - -NOTE: Polyamorous mode is only available when using pair version 1. - -In polyamorous mode a socket can support many one-to-one connections. -In this mode, the application must -choose the remote peer to receive an outgoing message by setting the -xref:nng_pipe.5.adoc[`nng_pipe`] to use for the outgoing message with -the xref:nng_msg_set_pipe.3.adoc[`nng_msg_set_pipe()`] function. - -If no remote peer is specified by the sender, then the protocol will select -any available connected peer. - -Most often the value of the outgoing pipe will be obtained from an incoming -message using the xref:nng_msg_get_pipe.3.adoc[`nng_msg_get_pipe()`] function, -such as when replying to an incoming message. - -NOTE: Directed send _only_ works with directly connected peers. -It will not function across xref:nng_device.3.adoc[device] proxies. - -In order to prevent head-of-line blocking, if the peer on the given pipe -is not able to receive (or the pipe is no longer available, such as if the -peer has disconnected), then the message will be discarded with no notification -to the sender. - -=== Protocol Options - -The following protocol-specific options are available. - -xref:nng_options.5.adoc#NNG_OPT_MAXTTL[`NNG_OPT_MAXTTL`]:: - - (`int`, version 1 only). Maximum time-to-live. - -((`NNG_OPT_PAIR1_POLY`)):: - - (`bool`, version 1 only) This option is no longer supported. - Formerly it was used to configure _polyamorous_ mode, but that mode - is now established by using the `nng_pair1_open_poly()` function. - -=== Protocol Headers - -Version 0 of the pair protocol has no protocol-specific headers. - -Version 1 of the pair protocol uses a single 32-bit unsigned value. The -low-order (big-endian) byte of this value contains a "hop" count, and is -used in conjunction with the -xref:nng_options.5.adoc#NNG_OPT_MAXTTL[`NNG_OPT_MAXTTL`] option to guard against -device forwarding loops. -This value is initialized to 1, and incremented each time the message is -received by a new node. - -== SEE ALSO - -[.text-left] -xref:nng_pair_open.3.adoc[nng_pair_open(3)], -xref:nng_options.5.adoc[nng_options(5)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_pub.7.adoc b/docs/man/nng_pub.7.adoc deleted file mode 100644 index fcebd417..00000000 --- a/docs/man/nng_pub.7.adoc +++ /dev/null @@ -1,69 +0,0 @@ -= nng_pub(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_pub - publisher protocol - -== SYNOPSIS - -[source,c] ----- -#include <nng/protocol/pubsub0/pub.h> ----- - -== DESCRIPTION - -(((protocol, _pub_))) -The ((_pub_ protocol)) is one half of a ((publisher))/subscriber pattern. -In this pattern, a publisher sends data, which is broadcast to all -subscribers. -The subscribing applications only see the data to which -they have subscribed. - -The _pub_ protocol is the publisher side, and the -xref:nng_sub.7.adoc[_sub_] protocol is the subscriber side. - -NOTE: In this implementation, the publisher delivers all messages to all -subscribers. -The subscribers maintain their own subscriptions, and filter them locally. -Thus, this pattern should not be used in an attempt to reduce bandwidth -consumption. - -The topics that subscribers subscribe to is just the first part of -the message body. -Applications should construct their messages accordingly. - -=== Socket Operations - -The xref:nng_pub_open.3.adoc[`nng_pub0_open()`] functions create a publisher socket. -This socket may be used to send messages, but is unable to receive them. -Attempts to receive messages will result in `NNG_ENOTSUP`. - -=== 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 _pub_ protocol has no protocol-specific options. - -=== Protocol Headers - -The _pub_ protocol has no protocol-specific headers. - -== SEE ALSO - -[.text-left] -xref:nng_pub_open.3.adoc[nng_pub_open(3)], -xref:nng_sub.7.adoc[nng_sub(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_pull.7.adoc b/docs/man/nng_pull.7.adoc deleted file mode 100644 index 0b325dab..00000000 --- a/docs/man/nng_pull.7.adoc +++ /dev/null @@ -1,65 +0,0 @@ -= nng_pull(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_pull - pull protocol - -== SYNOPSIS - -[source,c] ----- -#include <nng/protocol/pipeline0/pull.h> ----- - -== DESCRIPTION - -(((protocol, _pull_))) -The ((_pull_ protocol)) is one half of a ((pipeline pattern)). -The other half is the xref:nng_push.7.adoc[_push_] protocol. - -In the pipeline pattern, pushers distribute messages to pullers. -Each message sent -by a pusher will be sent to one of its peer pullers, -chosen in a round-robin fashion -from the set of connected peers available for receiving. -This property makes this pattern useful in ((load-balancing)) scenarios. - -=== Socket Operations - -The xref:nng_pull_open.3.adoc[`nng_pull0_open()`] functions create a puller socket. -This socket may be used to receive messages, but is unable to send them. -Attempts to send messages will result in `NNG_ENOTSUP`. - -When receiving messages, the _pull_ protocol accepts messages as -they arrive from peers. -If two peers both have a message ready, the -order in which messages are handled is undefined. - -=== 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 _pull_ protocol has no protocol-specific options. - -=== Protocol Headers - -The _pull_ protocol has no protocol-specific headers. - -== SEE ALSO - -[.text-left] -xref:nng_pull_open.3.adoc[nng_pull_open(3)], -xref:nng_push.7.adoc[nng_push(7)], -xref:nng.7.adoc[nng(7)], diff --git a/docs/man/nng_push.7.adoc b/docs/man/nng_push.7.adoc deleted file mode 100644 index b630c2bb..00000000 --- a/docs/man/nng_push.7.adoc +++ /dev/null @@ -1,80 +0,0 @@ -= nng_push(7) -// -// Copyright 2020 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_push - push protocol - -== SYNOPSIS - -[source,c] ----- -#include <nng/protocol/pipeline0/push.h> ----- - -== DESCRIPTION - -(((protocol, _push_))) -The ((_push_ protocol)) is one half of a ((pipeline pattern)). -The other side is the xref:nng_pull.7.adoc[_pull_] protocol. - -In the pipeline pattern, pushers distribute messages to pullers. -Each message sent by a pusher will be sent to one of its peer pullers, -chosen in a round-robin fashion -from the set of connected peers available for receiving. -This property makes this pattern useful in ((load-balancing)) scenarios. - -=== Socket Operations - -The xref:nng_push_open.3.adoc[`nng_push0_open()`] call creates a pusher socket. -This socket may be used to send messages, but is unable to receive them. -Attempts to receive messages will result in `NNG_ENOTSUP`. - -Send operations will observe flow control (back-pressure), so that -only peers capable of accepting a message will be considered. -If no peer is available to receive a message, then the send operation will -wait until one is available, or the operation times out. - -NOTE: Although the pipeline protocol honors flow control, and attempts -to avoid dropping messages, no guarantee of delivery is made. -Furthermore, as there is no capability for message acknowledgment, -applications that need reliable delivery are encouraged to consider the -xref:nng_req.7.adoc[_req_] protocol instead. - -=== 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 - -xref:nng_options.5.adoc#NNG_OPT_SENDBUF[`NNG_OPT_SENDBUF`]:: - - (`int`, 0 - 8192) - Normally this is set to zero, indicating that send operations are unbuffered. - In unbuffered operation, send operations will wait until a suitable peer is available to receive the message. - If this is set to a positive value (up to 8192), then an intermediate buffer is - provided for the socket with the specified depth (in messages). - -NOTE: Transport layer buffering may occur in addition to any socket - buffer determined by this option. - -=== Protocol Headers - -The _push_ protocol has no protocol-specific headers. - -== SEE ALSO - -[.text-left] -xref:nng_push_open.3.adoc[nng_push(3)], -xref:nng_pull.7.adoc[nng_pull(7)], -xref:nng_req.7.adoc[nng_req(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_rep.7.adoc b/docs/man/nng_rep.7.adoc deleted file mode 100644 index ea40eb3a..00000000 --- a/docs/man/nng_rep.7.adoc +++ /dev/null @@ -1,86 +0,0 @@ -= nng_rep(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_rep - reply protocol - -== SYNOPSIS - -[source,c] ----- -#include <nng/protocol/reqrep0/rep.h> ----- - -== DESCRIPTION - -(((protocol, _rep_))) -The ((_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 requester will keep retrying until -a reply is received. - -The _rep_ protocol is the replier side, and the -xref:nng_req.7.adoc[_req_] protocol is the requester side. - -=== Socket Operations - -The xref:nng_rep_open.3.adoc[`nng_rep0_open()`] functions create a replier 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. - -Send operations will result in `NNG_ESTATE` if no corresponding request -was previously received. - -Likewise, only one receive operation may be pending at a time. -Any additional concurrent receive operations will result in `NNG_ESTATE`. - -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()`]. - -Each context may have at most one outstanding request, and operates -independently of 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 _rep_ protocol has no protocol-specific options. - -==== Protocol Headers - -(((backtrace))) -The _rep_ protocol uses a _backtrace_ in the header. -This is more fully documented in the xref:nng_req.7.adoc[_req_] manual. - -== SEE ALSO - -[.text-left] -xref:nng_rep_open.3.adoc[nng_rep_open(3)], -xref:nng.7.adoc[nng(7)], -xref:nng_req.7.adoc[nng_req(7)] 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)] diff --git a/docs/man/nng_respondent.7.adoc b/docs/man/nng_respondent.7.adoc deleted file mode 100644 index f6f1538f..00000000 --- a/docs/man/nng_respondent.7.adoc +++ /dev/null @@ -1,91 +0,0 @@ -= nng_respondent(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_respondent - respondent protocol - -== SYNOPSIS - -[source,c] ----- -#include <nng/protocol/survey0/respond.h> ----- - -== DESCRIPTION - -(((protocol, _respondent_))) -The ((_respondent_ protocol)) is one half of a ((survey pattern)). -In this pattern, a surveyor sends a survey, which is broadcast to all -peer respondents. -The respondents then have a chance to reply (but are not obliged to reply). -The survey itself is a timed event, so that responses -received after the survey has finished are discarded. - -TIP: This protocol is useful in solving voting problems, such as leader -election in cluster configurations, as well as certain kinds of service -discovery problems. - -The _respondent_ protocol is the respondent side, and the -xref:nng_surveyor.7.adoc[_surveyor_] protocol is the surveyor side. - -=== Socket Operations - -The xref:nng_respondent_open.3.adoc[`nng_respondent0_open()`] functions create a -respondent socket. -This socket may be used to receive messages, and then to send replies. -A reply can only be sent after receiving a survey, and generally the -reply will be sent to surveyor from whom the last survey was received. - -Respondents may discard a survey by simply not replying to it. - -Raw mode sockets (set with xref:nng_options.5.adoc#NNG_OPT_RAW[`NNG_OPT_RAW`]) -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()`]. - -Incoming surveys will be routed to and received by only one context. -Additional surveys may be received by other contexts in parallel. -Replies made using a context will be returned to the the surveyor that -issued the survey most recently received by that context. -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. -An earlier and incompatible version of the protocol was used in older -pre-releases of http://nanomsg.org[nanomsg], but was not released in any -production version.) - -=== Protocol Options - -The _respondent_ protocol has no protocol-specific options. - -=== Protocol Headers - -(((backtrace))) -The _respondent_ protocol uses a _backtrace_ in the header. -This is more fully documented in the xref:nng_surveyor.7.adoc[_surveyor_] manual. - -// TODO: Insert reference to RFC. - -== SEE ALSO - -[.text-left] -xref:nng_respondent_open.3.adoc[nng_respondent_open(3)], -xref:nng_surveyor.7.adoc[nng_surveyor(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_sub.7.adoc b/docs/man/nng_sub.7.adoc deleted file mode 100644 index b362c656..00000000 --- a/docs/man/nng_sub.7.adoc +++ /dev/null @@ -1,99 +0,0 @@ -= nng_sub(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_sub - subscriber protocol - -== SYNOPSIS - -[source,c] ----- -#include <nng/nng.h> -#include <nng/protocol/pubsub0/sub.h> ----- - -== DESCRIPTION - -(((protocol, _sub_))) -The ((_sub_ protocol)) is one half of a publisher/((subscriber)) pattern. -In this pattern, a publisher sends data, which is broadcast to all subscribers. -The subscribing applications only see the data to which they have subscribed. - -The _sub_ protocol is the subscriber side, and the -xref:nng_pub.7.adoc[_pub_] protocol is the publisher side. - -NOTE: In this implementation, the publisher delivers all messages to all -subscribers. -The subscribers maintain their own subscriptions, and filter them locally. -Thus, this pattern should not be used in an attempt to -reduce bandwidth consumption. - -The topics that subscribers subscribe to is just the first part of -the message body. -Applications should construct their messages accordingly. - -=== Socket Operations - -The xref:nng_sub_open.3.adoc[`nng_sub0_open()`] functions create a subscriber socket. -This socket may be used to receive messages, but is unable to send them. -Attempts to send messages will result in `NNG_ENOTSUP`. - -=== 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_SUB_SUBSCRIBE`))(((subscribe))):: - - This option registers a topic that the subscriber is interested in. - The option is write-only, and takes an array of bytes, of arbitrary size. - Each incoming message is checked against the list of subscribed topics. - If the body begins with the entire set of bytes in the topic, then the - message is accepted. If no topic matches, then the message is - discarded. -+ -NOTE: This option is a byte array. Thus if you use -xref:nng_socket_set.3.adoc[`nng_socket_set_string()`] the `NUL` terminator byte will -be included in the topic. -If that isn't desired, consider using -xref:nng_socket_set.3.adoc[`nng_socket_set()`] and using `strlen()` of the topic -as the topic size. -+ -TIP: To receive all messages, an empty topic (zero length) can be used. - -((`NNG_OPT_SUB_UNSUBSCRIBE`)):: - - This option, also write-only, removes a topic from the subscription list. - Note that if the topic was not previously subscribed to with - `NNG_OPT_SUB_SUBSCRIBE` then an `NNG_ENOENT` error will result. - -((`NNG_OPT_SUB_PREFNEW`)):: - - (`bool`) - This read/write option specifies the behavior of the subscriber when the queue is full. - When `true` (the default), the subscriber will make room in the queue by removing the oldest message. - When `false`, the subscriber will reject messages if the message queue does not have room. - -=== Protocol Headers - -The _sub_ protocol has no protocol-specific headers. - -== SEE ALSO - -[.text-left] -xref:nng_sub_open.3.adoc[nng_sub_open(3)], -xref:nng_pub.7.adoc[nng_pub(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_surveyor.7.adoc b/docs/man/nng_surveyor.7.adoc deleted file mode 100644 index 6b38c0eb..00000000 --- a/docs/man/nng_surveyor.7.adoc +++ /dev/null @@ -1,149 +0,0 @@ -= nng_surveyor(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_surveyor - surveyor protocol - -== SYNOPSIS - -[source,c] ----- -#include <nng/nng.h> -#include <nng/protocol/survey0/survey.h> ----- - -== DESCRIPTION - -(((protocol, _surveyor_))) -The ((_surveyor_ protocol)) is one half of a ((survey pattern)). -In this pattern, a surveyor sends a survey, which is broadcast to all -peer respondents. -The respondents then have a chance to reply (but are not obliged to reply). -The survey itself is a timed event, so that responses -received after the survey has finished are discarded. - -TIP: This protocol is useful in solving voting problems, such as -((leader election)) in cluster configurations, as well as certain kinds of -((service discovery)) problems. - -The _surveyor_ protocol is the surveyor side, and the -xref:nng_respondent.7.adoc[_respondent_] protocol is the respondent side. - -=== Socket Operations - -The xref:nng_surveyor_open.3.adoc[`nng_surveyor0_open()`] -functions create a surveyor socket. -This socket may be used to send messages (surveys), and then to receive replies. -A reply can only be received after sending a survey. -A surveyor can normally expect to receive at most one reply from each responder. -(Messages can be duplicated in some topologies, -so there is no guarantee of this.) - -Attempts to receive on a socket with no outstanding survey will result -in `NNG_ESTATE`. -If the survey times out while the surveyor is waiting -for replies, then the result will be `NNG_ETIMEDOUT`. - -Only one survey can be outstanding at a time; sending another survey will -cancel the prior one, and any responses from respondents from the prior -survey that arrive after this will be discarded. - -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()`]. - -Each context can initiate its own surveys, and it will receive only -responses to its own outstanding surveys. -Other contexts on the same socket may have overlapping surveys -operating at the same time. - -Each of these may have their own timeouts established with -`NNG_OPT_SURVEYOR_SURVEYTIME`. - -Additionally, sending a survey on a context will only cancel an outstanding -survey on the same context. - -NOTE: Due to the best-effort nature of this protocol, if too may contexts -are attempting to perform surveys simultaneously, it is possible for either -individual outgoing surveys or incoming responses to be lost. - -=== Protocol Versions - -Only version 0 of this protocol is supported. -(At the time of writing, no other versions of this protocol have been defined. -An earlier and incompatible version of the protocol was used in older -pre-releases of -http://nanomsg.org[nanomsg], but was not released in any production -version.) - -=== Protocol Options - -The following protocol-specific options is available. - -((`NNG_OPT_SURVEYOR_SURVEYTIME`)):: - - (xref:nng_duration.5.adoc[`nng_duration`]) Duration of surveys. - 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 expires will result in `NNG_ETIMEDOUT`. - -=== Protocol Headers - -(((backtrace))) -This form uses a stack of 32-bit big-endian identifiers. -There *must* be at least one identifier, the __survey 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 survey ID. -These will be distinguishable from the survey ID by having their most -significant bit clear. - -When a survey 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 response.) - -When a response message is created, it is created using the same headers -that the survey 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 response finally arrives back at the initiating surveyor, it -should have only a single element in the message, which will be the -survey ID it originally used for the request. - -More detail can be found in the -https://github.com/nanomsg/nanomsg/blob/master/rfc/sp-surveyor-01.txt[RFC sp-surveyor-01] -document. - -== SEE ALSO - -[.text-left] -xref:nng_surveyor_open.3.adoc[nng_surveyor_open(3)], -xref:nng_respondent.7.adoc[nng_respondent(7)], -xref:nng.7.adoc[nng(7)] |