doc/go1.13: mention confusion between keep-alive timeout and deadline

Updates golang#31449 Change-Id: I4d7075b20cd8171bc792e40b388f4215264a3317 Reviewed-on: https://go-review.googlesource.com/c/go/+/188819 Reviewed-by: Filippo Valsorda <[email protected]>
kkishi · Aug 2, 2019 · 55e23cb · 55e23cb
1 parent 07b3e62
commit 55e23cb
Showing 1 changed file with 18 additions and 0 deletions.
diff --git a/doc/go1.13.html b/doc/go1.13.html
@@ -707,6 +707,24 @@ <h3 id="minor_library_changes">Minor changes to the library</h3>
     <p><!-- CL 170678 -->
       The new field <a href="/pkg/net/#ListenConfig.KeepAlive"><code>ListenConfig.KeepAlive</code></a>
       specifies the keep-alive period for network connections accepted by the listener.
+      If this field is 0 (the default) TCP keep-alives will be enabled.
+      To disable them, set it to a negative value.
+    </p>
+    <p>
+      Note that the error returned from I/O on a connection that was
+      closed by a keep-alive timeout will have a
+      <code>Timeout</code> method that returns <code>true</code> if called.
+      This can make a keep-alive error difficult to distinguish from
+      an error returned due to a missed deadline as set by the
+      <a href="/pkg/net#Conn"><code>SetDeadline</code></a>
+      method and similar methods.
+      Code that uses deadlines and checks for them with
+      the <code>Timeout</code> method or
+      with <a href="/pkg/os/#IsTimeout"><code>os.IsTimeout</code></a>
+      may want to disable keep-alives, or
+      use <code>errors.Is(syscall.ETIMEDOUT)</code> (on Unix systems)
+      which will return true for a keep-alive timeout and false for a
+      deadline timeout.
     </p>
 
 </dl><!-- net -->