From 31679fe04c521b78b5bb2bda42f2f9bc22575895 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Thu, 2 Nov 2017 16:13:47 -0700 Subject: man page updates for 0.0.0 --- man/v0.0.0/libnng.html | 10 +- man/v0.0.0/nng_bus.html | 640 +++++++++++++++++++++++++++++++++++++++ man/v0.0.0/nng_inproc.html | 29 +- man/v0.0.0/nng_ipc.html | 662 ++++++++++++++++++++++++++++++++++++++++ man/v0.0.0/nng_pair.html | 733 +++++++++++++++++++++++++++++++++++++++++++++ man/v0.0.0/nng_pub.html | 10 +- man/v0.0.0/nng_pull.html | 613 +++++++++++++++++++++++++++++++++++++ man/v0.0.0/nng_push.html | 631 ++++++++++++++++++++++++++++++++++++++ man/v0.0.0/nng_sub.html | 10 +- man/v0.0.0/nng_tcp.html | 704 +++++++++++++++++++++++++++++++++++++++++++ 10 files changed, 4012 insertions(+), 30 deletions(-) create mode 100644 man/v0.0.0/nng_bus.html create mode 100644 man/v0.0.0/nng_ipc.html create mode 100644 man/v0.0.0/nng_pair.html create mode 100644 man/v0.0.0/nng_pull.html create mode 100644 man/v0.0.0/nng_push.html create mode 100644 man/v0.0.0/nng_tcp.html diff --git a/man/v0.0.0/libnng.html b/man/v0.0.0/libnng.html index 0498d5ae..73d9cfdd 100644 --- a/man/v0.0.0/libnng.html +++ b/man/v0.0.0/libnng.html @@ -520,14 +520,6 @@ intended to solve common communication problems in distributed applications.

create and start a listener

-

nng_protocol(3)

-

return the protocol number for socket

- - -

nng_peer(3)

-

return peer protocol number for socket

- -

nng_recv(3)

receive data

@@ -802,7 +794,7 @@ Copyright 2017 Capitar IT Group BV

diff --git a/man/v0.0.0/nng_bus.html b/man/v0.0.0/nng_bus.html new file mode 100644 index 00000000..a91dc183 --- /dev/null +++ b/man/v0.0.0/nng_bus.html @@ -0,0 +1,640 @@ +--- +version: 0.0.0 +layout: default +--- + + + + + + + + +nng_bus(7) + + + + + + + +
+
+

SYNOPSIS

+
+
+
+
#include <nng/protocol/bus0/bus.h>
+
+int nng_bus0_open(nng_socket *s);
+
+
+
+
+
+

DESCRIPTION

+
+
+

The nng_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.

+
+
+ + + + + +
+ + +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.

+
+
+ + + + + +
+ + +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 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.

+
+
+
+

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_bus protocol has no protocol-specific options.

+
+
+
+

Protocol Headers

+
+

The nng_bus protocol has no protocol-specific headers.

+
+
+
+
+
+

AUTHORS

+ +
+
+

SEE ALSO

+
+
+

nng(7)

+
+
+
+
+ +
+
+

Copyright 2017 Garrett D’Amore
+Copyright 2017 Capitar IT Group BV

+
+
+

This document is supplied under the terms of the +MIT License.

+
+
+
+
+ + + diff --git a/man/v0.0.0/nng_inproc.html b/man/v0.0.0/nng_inproc.html index 41335d4a..3ee60cc9 100644 --- a/man/v0.0.0/nng_inproc.html +++ b/man/v0.0.0/nng_inproc.html @@ -547,8 +547,7 @@ no extra steps to use it should be necessary.

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 @@ -568,17 +567,33 @@ that URI.

-
#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"
+    //
 }
+
+ + + + + + + + + +
1The values of these macros may change, so applications +should avoid depending upon their values and instead use them symbolically.
2Other 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.

@@ -624,7 +639,7 @@ Copyright 2017 Capitar IT Group BV

diff --git a/man/v0.0.0/nng_ipc.html b/man/v0.0.0/nng_ipc.html new file mode 100644 index 00000000..1848a6dc --- /dev/null +++ b/man/v0.0.0/nng_ipc.html @@ -0,0 +1,662 @@ +--- +version: 0.0.0 +layout: default +--- + + + + + + + + +nng_ipc(7) + + + + + + + +
+
+

SYNOPSIS

+
+
+
+
#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.

+
+
+

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.

+
+
+ + + + + +
+ + +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:

+
+
+
+
#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;
+
+
+
+ + + + + + + + + +
1The values of these macros may change, so applications +should avoid depending upon their values and instead use them symbolically.
2Other 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.[1]

+
+
+
+
+
+

AUTHORS

+ +
+
+

SEE ALSO

+
+
+

nng(7)

+
+
+
+
+ +
+
+

Copyright 2017 Garrett D’Amore
+Copyright 2017 Capitar IT Group BV

+
+
+

This document is supplied under the terms of the +MIT License.

+
+
+
+
+
+
+
+1. Options for security attributes and credentials are planned. +
+
+ + + diff --git a/man/v0.0.0/nng_pair.html b/man/v0.0.0/nng_pair.html new file mode 100644 index 00000000..f118e59a --- /dev/null +++ b/man/v0.0.0/nng_pair.html @@ -0,0 +1,733 @@ +--- +version: 0.0.0 +layout: default +--- + + + + + + + + +nng_pair(7) + + + + + + + +
+
+

SYNOPSIS

+
+
+
Version 0
+
+
#include <nng/protocol/pair0/pair.h>
+
+int nng_pair0_open(nng_socket *s);
+
+
+
+
Version 1
+
+
#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.

+
+
+ + + + + +
+ + +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(3)) or raw mode sockets where +messages may be discarded. Applications that require reliable delivery +semantics should consider using 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.

+
+
+ + + + + +
+ + +Use version 0 if you need to communicate with other implementations, +including the legacy nanomsg library or +mangos. +
+
+
+

Version 1 of the protocol offers improved protection against loops when +used with nng_device(3). It also offers polyamorous +mode for forming multiple partnerships on a single socket.

+
+
+ + + + + +
+ + +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(3) function.

+
+
+

Most often the value of the outgoing pipe ID will be obtained from an incoming +message using the 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.

+
+ + + + + +
+ + +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

+ +
+
+

SEE ALSO

+
+
+

nng(7)

+
+
+
+
+ +
+
+

Copyright 2017 Garrett D’Amore
+Copyright 2017 Capitar IT Group BV

+
+
+

This document is supplied under the terms of the +MIT License.

+
+
+
+
+ + + diff --git a/man/v0.0.0/nng_pub.html b/man/v0.0.0/nng_pub.html index 52dcf557..00fc7a95 100644 --- a/man/v0.0.0/nng_pub.html +++ b/man/v0.0.0/nng_pub.html @@ -516,12 +516,8 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
-
#include <nng/protocol/pubsub/pubsub.h>
+
#include <nng/protocol/pubsub0/pub.h>
 
-#define NNG_PROTO_PUB_V0 32
-#define NNG_PROTO_PUB NNG_PROTO_PUB_V0
-
-int nng_pub_open(nng_socket *s);
 int nng_pub0_open(nng_socket *s);
@@ -563,7 +559,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.

@@ -623,7 +619,7 @@ Copyright 2017 Capitar IT Group BV

diff --git a/man/v0.0.0/nng_pull.html b/man/v0.0.0/nng_pull.html new file mode 100644 index 00000000..acd43b81 --- /dev/null +++ b/man/v0.0.0/nng_pull.html @@ -0,0 +1,613 @@ +--- +version: 0.0.0 +layout: default +--- + + + + + + + + +nng_pull(7) + + + + + + + +
+
+

SYNOPSIS

+
+
+
+
#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(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

+ +
+
+

SEE ALSO

+ +
+
+ +
+
+

Copyright 2017 Garrett D’Amore
+Copyright 2017 Capitar IT Group BV

+
+
+

This document is supplied under the terms of the +MIT License.

+
+
+
+
+ + + diff --git a/man/v0.0.0/nng_push.html b/man/v0.0.0/nng_push.html new file mode 100644 index 00000000..dea2567f --- /dev/null +++ b/man/v0.0.0/nng_push.html @@ -0,0 +1,631 @@ +--- +version: 0.0.0 +layout: default +--- + + + + + + + + +nng_push(7) + + + + + + + +
+
+

SYNOPSIS

+
+
+
+
#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(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.

+
+
+ + + + + +
+ + +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(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

+ +
+
+

SEE ALSO

+ +
+
+ +
+
+

Copyright 2017 Garrett D’Amore
+Copyright 2017 Capitar IT Group BV

+
+
+

This document is supplied under the terms of the +MIT License.

+
+
+
+
+ + + diff --git a/man/v0.0.0/nng_sub.html b/man/v0.0.0/nng_sub.html index a35ca64b..a019ecf6 100644 --- a/man/v0.0.0/nng_sub.html +++ b/man/v0.0.0/nng_sub.html @@ -516,12 +516,8 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
-
#include <nng/protocol/pubsub/pubsub.h>
+
#include <nng/protocol/pubsub0/sub.h>
 
-#define NNG_PROTO_SUB_V0 33
-#define NNG_PROTO_SUB NNG_PROTO_SUB_V0
-
-int nng_sub_open(nng_socket *s);
 int nng_sub0_open(nng_socket *s);
@@ -563,7 +559,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.

@@ -654,7 +650,7 @@ Copyright 2017 Capitar IT Group BV

diff --git a/man/v0.0.0/nng_tcp.html b/man/v0.0.0/nng_tcp.html new file mode 100644 index 00000000..a6de2083 --- /dev/null +++ b/man/v0.0.0/nng_tcp.html @@ -0,0 +1,704 @@ +--- +version: 0.0.0 +layout: default +--- + + + + + + + + +nng_tcp(7) + + + + + + + +
+
+

SYNOPSIS

+
+
+
+
#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.

+
+
+

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.

+
+
+ + + + + +
+ + +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.[1] +
+
+
+

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. +
  3. +

    tcp://*:9999

    +
  4. +
  5. +

    tcp://:9999

    +
  6. +
+
+
+

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:

+
+
+
+
#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;
+
+
+
+ + + + + + + + + +
1The values of these macros may change, so applications +should avoid depending upon their values and instead use them symbolically.
2Other 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.[2]

+
+
+
+
+
+

AUTHORS

+ +
+
+

SEE ALSO

+
+
+

nng(7)

+
+
+
+
+ +
+
+

Copyright 2017 Garrett D’Amore
+Copyright 2017 Capitar IT Group BV

+
+
+

This document is supplied under the terms of the +MIT License.

+
+
+
+
+
+
+
+1. This is a bug and will likely be fixed in the future. +
+
+2. Options for TCP keepalive, linger, and nodelay are planned. +
+
+ + + -- cgit v1.2.3-70-g09d2