diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/nng_bus.adoc | 6 | ||||
| -rw-r--r-- | docs/nng_inproc.adoc | 17 | ||||
| -rw-r--r-- | docs/nng_ipc.adoc | 110 | ||||
| -rw-r--r-- | docs/nng_pair.adoc | 155 | ||||
| -rw-r--r-- | docs/nng_pub.adoc | 6 | ||||
| -rw-r--r-- | docs/nng_pull.adoc | 85 | ||||
| -rw-r--r-- | docs/nng_push.adoc | 93 | ||||
| -rw-r--r-- | docs/nng_sub.adoc | 6 | ||||
| -rw-r--r-- | docs/nng_tcp.adoc | 137 |
9 files changed, 597 insertions, 18 deletions
diff --git a/docs/nng_bus.adoc b/docs/nng_bus.adoc index 03c43381..dd83062b 100644 --- a/docs/nng_bus.adoc +++ b/docs/nng_bus.adoc @@ -21,11 +21,9 @@ SYNOPSIS [source,c] ---------- -#include <nng/protocol/bus/bus.h> +#include <nng/protocol/bus0/bus.h> -int nng_bus_open(nng_socket *s); int nng_bus0_open(nng_socket *s); - ---------- DESCRIPTION @@ -57,7 +55,7 @@ likely that message loss is to occur. Socket Operations ~~~~~~~~~~~~~~~~~ -The `nng_bus_open()` call creates a bus socket. This socket +The `nng_bus0_open()` call creates a bus socket. This socket may be used to send and receive messages. Sending messages will attempt to deliver to each directly connected peer. diff --git a/docs/nng_inproc.adoc b/docs/nng_inproc.adoc index 9e044f6d..a6d83c95 100644 --- a/docs/nng_inproc.adoc +++ b/docs/nng_inproc.adoc @@ -47,8 +47,7 @@ URI Format This transport uses URIs using the scheme `inproc://`, followed by an arbitrary string of text, terminated by a `NUL` byte. The -entire URI must be less than `NNG_MAXADDRLEN` bytes long, including -the terminating `NUL`. +entire URI must be less than `NNG_MAXADDRLEN` bytes long. Multiple URIs can be used within the same application, and they will not interfere with one another. @@ -65,16 +64,22 @@ When using an `nng_sockaddr` structure, the actual structure is of type [source,c] -------- -#define NNG_AF_INPROC 1 +#define NNG_AF_INPROC 1 <1> #define NNG_MAXADDRLEN 128 -struct nng_sockaddr_inproc { +typedef nng_sockaddr_inproc { + // <2> uint16_t sa_family; // must be NNG_AF_INPROC - uint32_t sa_path[NNG_MAXADDRLEN]; // arbitrary "path" + char sa_path[NNG_MAXADDRLEN]; // arbitrary "path" + // } -------- +<1> The values of these macros may change, so applications +should avoid depending upon their values and instead use them symbolically. +<2> Other members may be present, but only those listed here +are suitable for application use. -The `sa_family` member will have the value `NNG_AF_INPROC` (1). +The `sa_family` member will have the value `NNG_AF_INPROC`. The `sa_path` member is an ASCIIZ string, and may contain any characters, terminated by a `NUL` byte. diff --git a/docs/nng_ipc.adoc b/docs/nng_ipc.adoc new file mode 100644 index 00000000..c5dac4f7 --- /dev/null +++ b/docs/nng_ipc.adoc @@ -0,0 +1,110 @@ +nng_ipc(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_ipc - IPC transport for nng + +SYNOPSIS +-------- + +[source,c] +---------- +#include <nng/transport/ipc/ipc.h> + +int nng_ipc_register(void); +---------- + +DESCRIPTION +----------- + +The _nng_ipc_ transport provides communication support between +_nng_ sockets within different processes on the same host. For POSIX +platforms, this is implemented using UNIX domain sockets. For Windows, +this is implemented using Windows Named Pipes. Other platforms may +have different implementation strategies. + +// We need to insert a reference to the nanomsg RFC. + +Registration +~~~~~~~~~~~~ + +The _ipc_ transport is generally built-in to the _nng_ core, so +no extra steps to use it should be necessary. + +URI Format +~~~~~~~~~~ + +This transport uses URIs using the scheme `ipc://`, followed by +a path name in the file system where the socket or named pipe +should be created. + +TIP: On Windows, all names are prefixed by `\.\pipe\` and do not +occupy the normal file system. On POSIX platforms, the path is +taken literally, and is relative to the current directory, unless +an extra leading `/` is provided. For example, `ipc://myname` refers +to the name `myname` in the current directory, whereas `ipc:///tmp/myname` +refers to `myname` located in `/tmp`. + +The entire URI must be less than `NNG_MAXADDRLEN` bytes long. + +Socket Address +~~~~~~~~~~~~~~ + +When using an `nng_sockaddr` structure, the actual structure is of type +`nng_sockaddr_ipc`. This is a `struct` type with the following definition: + +[source,c] +-------- +#define NNG_AF_IPC 2 <1> +#define NNG_MAXADDRLEN 128 + +typedef struct { + // ... <2> + uint16_t sa_family; // must be NNG_AF_IPC + char sa_path[NNG_MAXADDRLEN]; // arbitrary "path" + // ... +} nng_sockaddr_ipc; +-------- +<1> The values of these macros may change, so applications +should avoid depending upon their values and instead use them symbolically. +<2> Other members may be present, but only those listed here +are suitable for application use. + +The `sa_family` member will have the value `NNG_AF_IPC`. +The `sa_path` member is an ASCIIZ string, and may contain any legal +path name (platform-dependent), terminated by a `NUL` byte. + +Transport Options +~~~~~~~~~~~~~~~~~ + +The _ipc_ transport has no special +options.footnote:[Options for security attributes and credentials are planned.] + +AUTHORS +------- +link:mailto:garrett@damore.org[Garrett D'Amore] + +SEE ALSO +-------- +<<nng.adoc#,nng(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_pair.adoc b/docs/nng_pair.adoc new file mode 100644 index 00000000..b55000af --- /dev/null +++ b/docs/nng_pair.adoc @@ -0,0 +1,155 @@ +nng_pair(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_pair - pair protocol + +SYNOPSIS +-------- + +.Version 0 +[source,c] +---------- +#include <nng/protocol/pair0/pair.h> + +int nng_pair0_open(nng_socket *s); +---------- + +.Version 1 +[source,c] +---------- +#include <nng/protocol/pair1/pair.h> + +int nng_pair1_open(nng_socket *s); +---------- + +DESCRIPTION +----------- + +The _nng_pair_ protocol implements a peer-to-peer pattern, where +relationships between peers are one-to-one. + +Version 1 of this protocol supports an optional _polyamorous_ mode where a +peer can maintain multiple partnerships. Using this mode requires +some additional sophistication in the application. + +Socket Operations +~~~~~~~~~~~~~~~~~ + +The `nng_pair_open()` call creates 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 <<nng_device.adoc#,nng_device(3)>>) or raw mode sockets where +messages may be discarded. Applications that require reliable delivery +semantics should consider using <<nng_req.adoc#,nng_req(7)>> sockets, or +implement their own acknowledgement layer on top of pair sockets. + +In order to avoid head-of-line blocking conditions, _polyamorous_ mode pair +sockets (version 1 only) discard messages if they are unable to deliver them +to a peer. + +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 <<nng_device.adoc#,nng_device(3)>>. It also offers _polyamorous_ +mode for forming multiple partnerships on a single socket. + +NOTE: Version 1 of this protocol is considered experimental at this time. + +Polyamorous Mode +~~~~~~~~~~~~~~~~ + +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. + +In _polyamorous_ mode, which is only available with version 1, a socket can +support many one-to-one connections. In this mode, the application must +choose the remote peer to receive an ougoing message by setting the value +of the pipe ID on the outgoing message using +the <<nng_msg_set_pipe.adoc#,nng_msg_set_pipe(3)>> function. + +Most often the value of the outgoing pipe ID will be obtained from an incoming +message using the <<nng_msg_get_pipe.adoc#,nng_msg_get_pipe(3)>> function, +such as when replying to an incoming message. + +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. + +`NNG_OPT_PAIR1_POLY`:: + + (Version 1 only). This option enables the use of _polyamorous_ mode. + The value is read-write, and takes an integer boolean value. The default + false value (0) indicates that legacy monogamous mode should be used. + +`NNG_OPT_MAXTTL`:: + + (Version 1 only). 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. ++ +TIP: Each node along a forwarding path may have it's own value for the +maximum time-to-live, and performs its own checks before forwarding a message. +Therefore it is helpful if all nodes in the topology use the same value for +this option. + +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 conjuction with the `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. + +AUTHORS +------- +link:mailto:garrett@damore.org[Garrett D'Amore] + +SEE ALSO +-------- +<<nng.adoc#,nng(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_pub.adoc b/docs/nng_pub.adoc index d4db45ae..4c3b764b 100644 --- a/docs/nng_pub.adoc +++ b/docs/nng_pub.adoc @@ -21,11 +21,9 @@ SYNOPSIS [source,c] ---------- -#include <nng/protocol/pubsub/pubsub.h> +#include <nng/protocol/pubsub0/pub.h> -int nng_pub_open(nng_socket *s); int nng_pub0_open(nng_socket *s); - ---------- DESCRIPTION @@ -51,7 +49,7 @@ accordingly. Socket Operations ~~~~~~~~~~~~~~~~~ -The `nng_pub_open()` call creates a publisher socket. This socket +The `nng_pub0_open()` call creates 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`. diff --git a/docs/nng_pull.adoc b/docs/nng_pull.adoc new file mode 100644 index 00000000..17614a3d --- /dev/null +++ b/docs/nng_pull.adoc @@ -0,0 +1,85 @@ +nng_pull(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_pull - pull protocol + +SYNOPSIS +-------- + +[source,c] +---------- +#include <nng/protocol/pipeline0/pull.h> + +int nng_pull0_open(nng_socket *s); +---------- + +DESCRIPTION +----------- + +The _nng_pull_ protocol is one half of a pipeline pattern. The other half +is the <<nng_push.adoc#,nng_push(7)>> 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 `nng_pull0_open()` call creates 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 _nng_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 _nng_pull_ protocol has no protocol-specific options. + +Protocol Headers +~~~~~~~~~~~~~~~~ + +The _nng_pull_ protocol has no protocol-specific headers. + +AUTHORS +------- +link:mailto:garrett@damore.org[Garrett D'Amore] + +SEE ALSO +-------- +<<nng.adoc#,nng(7)>> +<<nng_push.adoc#,nng_push(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_push.adoc b/docs/nng_push.adoc new file mode 100644 index 00000000..faf783b6 --- /dev/null +++ b/docs/nng_push.adoc @@ -0,0 +1,93 @@ +nng_push(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_push - push protocol + +SYNOPSIS +-------- + +[source,c] +---------- +#include <nng/protocol/pipeline0/push.h> + +int nng_push0_open(nng_socket *s); +---------- + +DESCRIPTION +----------- + +The _nng_push_ protocol is one half of a pipeline pattern. The +other side is the <<nng_pull.adoc#,nng_pull(7)>> 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 `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 acknowledgement, applications that +need reliable delivery are encouraged to consider the +<<nng_req.adoc#,nng_req(7)>> 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 +~~~~~~~~~~~~~~~~ + +The _nng_push_ protocol has no protocol-specific options. + +Protocol Headers +~~~~~~~~~~~~~~~~ + +The _nng_push_ protocol has no protocol-specific headers. + +AUTHORS +------- +link:mailto:garrett@damore.org[Garrett D'Amore] + +SEE ALSO +-------- +<<nng.adoc#,nng(7)>> +<<nng_pull.adoc#,nng_pull(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_sub.adoc b/docs/nng_sub.adoc index 0b409904..5359acec 100644 --- a/docs/nng_sub.adoc +++ b/docs/nng_sub.adoc @@ -21,11 +21,9 @@ SYNOPSIS [source,c] ---------- -#include <nng/protocol/pubsub/pubsub.h> +#include <nng/protocol/pubsub0/sub.h> -int nng_sub_open(nng_socket *s); int nng_sub0_open(nng_socket *s); - ---------- DESCRIPTION @@ -51,7 +49,7 @@ accordingly. Socket Operations ~~~~~~~~~~~~~~~~~ -The `nng_sub_open()` call creates a subscriber socket. This socket +The `nng_sub0_open()` call creates 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`. diff --git a/docs/nng_tcp.adoc b/docs/nng_tcp.adoc new file mode 100644 index 00000000..a1d0cdab --- /dev/null +++ b/docs/nng_tcp.adoc @@ -0,0 +1,137 @@ +nng_tcp(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_tcp - TCP/IP transport for nng + +SYNOPSIS +-------- + +[source,c] +---------- +#include <nng/transport/tcp/tcp.h> + +int nng_tcp_register(void); +---------- + +DESCRIPTION +----------- + +The _nng_tcp_ transport provides communication support between +_nng_ sockets across a TCP/IP network. Both IPv4 and IPv6 +are supported when the underlying platform also supports it. + +// We need to insert a reference to the nanomsg RFC. + +Registration +~~~~~~~~~~~~ + +The _tcp_ transport is generally built-in to the _nng_ core, so +no extra steps to use it should be necessary. + +URI Format +~~~~~~~~~~ + +This transport uses URIs using the scheme `tcp://`, followed by +an IP address or hostname, followed by a colon and finally a +TCP port number. For example, to contact port 80 on the localhost +either of the following URIs could be used: `tcp://127.0.0.1:80` or +`tcp://localhost:80`. + +When specifying IPv6 addresses, the address must be enclosed in +square brackets (`[]`) to avoid confusion with the final colon +separating the port. + +For example, the same port 80 on the IPv6 loopback address ('::1') would +be specified as `tcp://[::1]:80`. + +NOTE: When using symbolic names, the name is resolved when the +name is first used. _nng_ won't become aware of changes in the +name resolution until restart, +usually.footnote:[This is a bug and will likely be fixed in the future.] + +The special value of 0 (`INADDR_ANY`) can be used for a listener +to indicate that it should listen on all interfaces on the host. +A short-hand for this form is to either omit the address, or specify +the asterisk (`*`) character. For example, the following three +URIs are all equivalent, and could be used to listen to port 9999 +on the host: + + 1. `tcp://0.0.0.0:9999` + 2. `tcp://*:9999` + 3. `tcp://:9999` + +The entire URI must be less than `NNG_MAXADDRLEN` bytes long. + +Socket Address +~~~~~~~~~~~~~~ + +When using an `nng_sockaddr` structure, the actual structure is either +of type `nng_sockaddr_in` (for IPv4) or `nng_sockaddr_in6` (for IPv6). +These are `struct` types with the following definitions: + +[source,c] +-------- +#define NNG_AF_INET 3 <1> +#define NNG_AF_INET6 4 +#define NNG_MAXADDRLEN 128 + +typedef struct { + // ... <2> + uint16_t sa_family; // must be NNG_AF_INET + uint16_t sa_port; // TCP port number + uint32_t sa_addr; + // ... +} nng_sockaddr_in; + +typedef struct { + // ... <2> + uint16_t sa_family; // must be NNG_AF_INET6 + uint16_t sa_port; // TCP port number + uint8_t sa_addr[16]; + // ... +} nng_sockaddr_in6; +-------- +<1> The values of these macros may change, so applications +should avoid depending upon their values and instead use them symbolically. +<2> Other members may be present, but only those listed here +are suitable for application use. + +The `sa_family` member will have the value `NNG_AF_INET` or `NNG_AF_INET6`. +The `sa_port` and `sa_addr` are the TCP port number and address, both in +network byte order (most significant byte is first). + +Transport Options +~~~~~~~~~~~~~~~~~ + +The _tcp_ transport has no special +options.footnote:[Options for TCP keepalive, linger, and nodelay are planned.] + +AUTHORS +------- +link:mailto:garrett@damore.org[Garrett D'Amore] + +SEE ALSO +-------- +<<nng.adoc#,nng(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]. |