From e22f9c9f23d69abbbf3acbd668a22df9664705a2 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Thu, 26 Apr 2018 19:30:35 -0700 Subject: man page updates for tip --- man/tip/nng_ctx.5.html | 17 ++++++- man/tip/nng_dialer.5.html | 17 ++++++- man/tip/nng_listener.5.html | 17 ++++++- man/tip/nng_options.5.html | 105 +++++++++++++++++++++++++++++++++++++------- man/tip/nng_pipe.5.html | 17 ++++++- man/tip/nng_socket.5.html | 13 +++--- man/tip/nng_tcp.7.html | 33 ++++++++------ man/tip/nng_tls.7.html | 16 +++++++ 8 files changed, 196 insertions(+), 39 deletions(-) (limited to 'man') diff --git a/man/tip/nng_ctx.5.html b/man/tip/nng_ctx.5.html index e5d16bed..f6252614 100644 --- a/man/tip/nng_ctx.5.html +++ b/man/tip/nng_ctx.5.html @@ -526,7 +526,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b 
#include <nng/nng.h>
 
-typedef uint32_t nng_ctx
+typedef struct nng_ctx_s nng_ctx
@@ -550,6 +550,21 @@ of any sent request, a timer to retry the request on failure, and so forth. A separate context on the same socket can have similar data, but corresponding to a completely different request.

+
+ + + + + +
+ + +The nng_ctx structure is always passed by value (both +for input parameters and return values), and should be treated opaquely. +Passing structures this way ensures gives the compiler a chance to perform +accurate type checks in functions passing values of this type. +
+

All contexts share the same socket, and so some options, as well as the underlying transport details, will be common to all contexts on that socket.

diff --git a/man/tip/nng_dialer.5.html b/man/tip/nng_dialer.5.html index 8d1992fe..77e85678 100644 --- a/man/tip/nng_dialer.5.html +++ b/man/tip/nng_dialer.5.html @@ -525,7 +525,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b 
#include <nng/nng.h>
 
-typedef uint32_t nng_dialer;
+typedef struct nng_dialer_s nng_dialer;
@@ -550,6 +550,21 @@ destroyed.

or nng_dial() functions, and are always “owned” by a single nng_socket.

+
+ + + + + +
+ + +The nng_dialer structure is always passed by value (both +for input parameters and return values), and should be treated opaquely. +Passing structures this way ensures gives the compiler a chance to perform +accurate type checks in functions passing values of this type. +
+
diff --git a/man/tip/nng_listener.5.html b/man/tip/nng_listener.5.html index 8ebfcfb6..1c6eeb5f 100644 --- a/man/tip/nng_listener.5.html +++ b/man/tip/nng_listener.5.html @@ -525,7 +525,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b 
#include <nng/nng.h>
 
-typedef uint32_t nng_listener;
+typedef struct nng_listener_s nng_listener;
@@ -546,6 +546,21 @@ server can have many connections to multiple clients simultaneously.

or nng_listen() functions, and are always “owned” by a single nng_socket.

+
+
+ + + + +
+ + +The nng_listener structure is always passed by value (both +for input parameters and return values), and should be treated opaquely. +Passing structures this way ensures gives the compiler a chance to perform +accurate type checks in functions passing values of this type. +
+
diff --git a/man/tip/nng_options.5.html b/man/tip/nng_options.5.html index 7eb5bfcf..d9ac65ea 100644 --- a/man/tip/nng_options.5.html +++ b/man/tip/nng_options.5.html @@ -529,21 +529,23 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b 
#include <nng/nng.h>
 
-#define NNG_OPT_SOCKNAME   "socket-name"
-#define NNG_OPT_RAW        "raw"
-#define NNG_OPT_RECVBUF    "recv-buffer"
-#define NNG_OPT_SENDBUF    "send-buffer"
-#define NNG_OPT_RECVFD     "recv-fd"
-#define NNG_OPT_SENDFD     "send-fd"
-#define NNG_OPT_RECVTIMEO  "recv-timeout"
-#define NNG_OPT_SENDTIMEO  "send-timeout"
-#define NNG_OPT_LOCADDR    "local-address"
-#define NNG_OPT_REMADDR    "remote-address"
-#define NNG_OPT_URL        "url"
-#define NNG_OPT_MAXTTL     "ttl-max"
-#define NNG_OPT_RECVMAXSZ  "recv-size-max"
-#define NNG_OPT_RECONNMINT "reconnect-time-min"
-#define NNG_OPT_RECONNMAXT "reconnect-time-max"
+#define NNG_OPT_SOCKNAME "socket-name" +#define NNG_OPT_RAW "raw" +#define NNG_OPT_RECVBUF "recv-buffer" +#define NNG_OPT_SENDBUF "send-buffer" +#define NNG_OPT_RECVFD "recv-fd" +#define NNG_OPT_SENDFD "send-fd" +#define NNG_OPT_RECVTIMEO "recv-timeout" +#define NNG_OPT_SENDTIMEO "send-timeout" +#define NNG_OPT_LOCADDR "local-address" +#define NNG_OPT_REMADDR "remote-address" +#define NNG_OPT_URL "url" +#define NNG_OPT_MAXTTL "ttl-max" +#define NNG_OPT_RECVMAXSZ "recv-size-max" +#define NNG_OPT_RECONNMINT "reconnect-time-min" +#define NNG_OPT_RECONNMAXT "reconnect-time-max" +#define NNG_OPT_TCP_NODELAY "tcp-nodelay" +#define NNG_OPT_TCP_KEEPALIVE "tcp-nodelay"
@@ -956,6 +958,79 @@ application.
+
+
+
NNG_OPT_TCP_NODELAY
+
+

(bool`) +This option is used to disable (or enable) the use of Nagle’s algorithm +for TCP connections. +When true (the default), messages are sent immediately by the underlying +TCP stream without waiting to gather more data. +When false, Nagle’s algorithm is enabled, and the TCP stream may +wait briefly in attempt to coalesce messages. +Nagle’s algorithm is useful on low-bandwidth connections to reduce overhead, +but it comes at a cost to latency.

+
+
+
+
+ + + + + +
+ + +This setting may apply to transports that are built on top of TCP. +See the transport documentation for each transport for details. +
+
+
+
+
NNG_OPT_TCP_KEEPALIVE
+
+

(bool`) +This option is used to enable the sending of keep-alive messages on +the underlying TCP stream. +This option is false by default. +When enabled, if no messages are seen for a period of time, then +a zero length TCP message is sent with the ACK flag set in an attempt +to tickle some traffic from the peer. +If none is still seen (after some platform-specific number of retries and +timeouts), then the remote peer is presumed dead, and the connection is closed.

+
+
+
+
+ + + + + +
+ + +This setting may apply to transports that are built on top of TCP. +See the transport documentation for each transport for details. +
+
+
+ + + + + +
+ + +This option has two purposes. +First, it can be used to detect dead peers on an otherwise quiescent network. +Second, it can be used to keep connection table entries in NAT and other +middleware from being expiring due to lack of activity. +
+
diff --git a/man/tip/nng_pipe.5.html b/man/tip/nng_pipe.5.html index 90878eeb..46d76fac 100644 --- a/man/tip/nng_pipe.5.html +++ b/man/tip/nng_pipe.5.html @@ -525,7 +525,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b 
#include <nng/nng.h>
 
-typedef uint32_t nng_pipe;
+typedef struct nng_pipe_s nng_pipe;
@@ -542,6 +542,21 @@ single TCP or IPC connection.) Pipes are associated with either the listener or dialer that created them, and therefore are also automatically associated with a single socket.

+
+ + + + + +
+ + +The nng_pipe structure is always passed by value (both +for input parameters and return values), and should be treated opaquely. +Passing structures this way ensures gives the compiler a chance to perform +accurate type checks in functions passing values of this type. +
+
diff --git a/man/tip/nng_socket.5.html b/man/tip/nng_socket.5.html index a6aa2d16..880e7cf8 100644 --- a/man/tip/nng_socket.5.html +++ b/man/tip/nng_socket.5.html @@ -525,7 +525,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b 
#include <nng/nng.h>
 
-typedef uint32_t nng_socket;
+typedef struct nng_socket_s nng_socket;
@@ -544,16 +544,17 @@ may be connected to multiple transports at the same time. However, a given socket will have exactly one “protocol” associated with it, and is responsible for any state machines or other protocol-specific logic.

-
+
- + -Although nng_socket is an integer data type, these objects are not -ordinary file descriptors, and can only be used with the functions that -explicitly indicate that it safe and appropropate to do so. +The nng_socket structure is always passed by value (both +for input parameters and return values), and should be treated opaquely. +Passing structures this way ensures gives the compiler a chance to perform +accurate type checks in functions passing values of this type.
diff --git a/man/tip/nng_tcp.7.html b/man/tip/nng_tcp.7.html index ba24b629..3b2d18ab 100644 --- a/man/tip/nng_tcp.7.html +++ b/man/tip/nng_tcp.7.html @@ -625,20 +625,25 @@ the actual structure is either of type

Transport Options

-
-

The nng_tcp transport has no special options.

-
-
- - - - - -
- - -Options for TCP keepalive, linger, and nodelay are planned. -
+
+
+
NNG_OPT_TCP_KEEPALIVE
+
+

This option is used to configure TCP keep-alives. +The value is of type bool, and defaults to false.

+
+
NNG_OPT_TCP_NODELAY
+
+

This option is used to configure Nagle’s algorithm. +When enabled (false), the underlying TCP stream will attempt +to buffer and coalesce messages before sending them on, waiting +a short interval to improve buffering and reduce the overhead +caused by sending too-small messages. +This comes at a cost to latency, and is not recommended with modern +high speed networks. +The value is of type bool and defaults to true.

+
+
diff --git a/man/tip/nng_tls.7.html b/man/tip/nng_tls.7.html index 24897141..9cb5cfa0 100644 --- a/man/tip/nng_tls.7.html +++ b/man/tip/nng_tls.7.html @@ -693,6 +693,22 @@ Note that setting these must be done before the transport is started.

+
NNG_OPT_TCP_KEEPALIVE
+
+

This option is used to configure TCP keep-alives. +The value is of type bool, and defaults to false.

+
+
NNG_OPT_TCP_NODELAY
+
+

This option is used to configure Nagle’s algorithm. +When enabled (false), the underlying TCP stream will attempt +to buffer and coalesce messages before sending them on, waiting +a short interval to improve buffering and reduce the overhead +caused by sending too-small messages. +This comes at a cost to latency, and is not recommended with modern +high speed networks. +The value is of type bool and defaults to true.

+
NNG_OPT_TLS_CONFIG

This option is used on an endpoint to access the underlying TLS -- cgit v1.2.3-70-g09d2