From 3de2b56557c80b310341c423492bd8ba895c1abe Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Thu, 26 Apr 2018 13:53:40 -0700 Subject: fixes #105 Want NNG_OPT_TCP_NODELAY option fixes #106 TCP keepalive tuning --- docs/man/nng_options.5.adoc | 67 +++++++++++++++++++++++++++++++++++---------- docs/man/nng_tcp.7.adoc | 18 ++++++++++-- docs/man/nng_tls.7.adoc | 16 +++++++++++ 3 files changed, 83 insertions(+), 18 deletions(-) (limited to 'docs/man') diff --git a/docs/man/nng_options.5.adoc b/docs/man/nng_options.5.adoc index d71a7b54..e6ed1f7b 100644 --- a/docs/man/nng_options.5.adoc +++ b/docs/man/nng_options.5.adoc @@ -19,21 +19,23 @@ nng_options - socket, dialer, listener, and pipe options ---- #include -#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" ---- == DESCRIPTION @@ -286,6 +288,41 @@ Accordingly it can only be used with dialers, listeners, and pipes. NOTE: Some transports will canonify URLs before returning them to the application. +[[NNG_OPT_TCP_NODELAY]] +((`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. + +NOTE: 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]] +((`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. + +NOTE: This setting may apply to transports that are built on top of TCP. +See the transport documentation for each transport for details. + +TIP: 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. + == SEE ALSO <>, diff --git a/docs/man/nng_tcp.7.adoc b/docs/man/nng_tcp.7.adoc index 9828b658..1d925b79 100644 --- a/docs/man/nng_tcp.7.adoc +++ b/docs/man/nng_tcp.7.adoc @@ -81,10 +81,22 @@ the actual structure is either of type === Transport Options -The _nng_tcp_ transport has no special options. +((`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`. -NOTE: Options for TCP keepalive, linger, and nodelay are planned. - == SEE ALSO <>, diff --git a/docs/man/nng_tls.7.adoc b/docs/man/nng_tls.7.adoc index da4adeb6..c783f739 100644 --- a/docs/man/nng_tls.7.adoc +++ b/docs/man/nng_tls.7.adoc @@ -110,6 +110,22 @@ the actual structure is either of type The following transport options are available. 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