File 0058-kernel-Expand-gen_tcp-close-docs-with-send... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 0058-kernel-Expand-gen_tcp-close-docs-with-send-text.patch of Package erlang (Revision 46c5166937f7e2f1fa2e44c030dd0337)

Currently displaying revision 46c5166937f7e2f1fa2e44c030dd0337 , Show latest

From 1b4dedb155a4fe6faf35448c2d119e391204701a Mon Sep 17 00:00:00 2001
From: Lukas Larsson <lukas@erlang.org>
Date: Thu, 16 Mar 2017 10:38:23 +0100
Subject: [PATCH] kernel: Expand gen_tcp:close docs with send text

This commit attempts to clarify some of the guarantees given by
the TCP standard when issuing close. This is quite a complex
topic so there are probably corner cases still left, but this
at least tells the user that things can go wrong when doing
a close.
---
 lib/kernel/doc/src/gen_tcp.xml | 17 +++++++++++++++++
 lib/kernel/doc/src/inet.xml    |  2 +-
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/lib/kernel/doc/src/gen_tcp.xml b/lib/kernel/doc/src/gen_tcp.xml
index e97db2006..bef8096ae 100644
--- a/lib/kernel/doc/src/gen_tcp.xml
+++ b/lib/kernel/doc/src/gen_tcp.xml
@@ -140,6 +140,23 @@ do_recv(Sock, Bs) ->
 <fsummary>Close a TCP socket.</fsummary>
 <desc>
 Closes a TCP socket.
+ Note that in most implementations of TCP, doing a <c>close</c> does
+ not guarantee that any data sent is delivered to the recipient before
+ the close is detected at the remote side. If you want to guarantee
+ delivery of the data to the recipient there are two common ways to
+ achieve this.
+ <list type="ordered">
+ <item>Use <seealso marker="#shutdown/2">
+ <c>gen_tcp:shutdown(Sock, write)</c></seealso> to signal that
+ no more data is to be sent and wait for the read side of the
+ socket to be closed.
+ </item>
+ <item>Use the socket option <seealso marker="inet#packet">
+ <c>{packet, N}</c></seealso> (or something similar) to make
+ it possible for the receiver to close the connection when it
+ knowns it has received all the data.
+ </item>
+ </list>
 </desc>
 </func>
 
diff --git a/lib/kernel/doc/src/inet.xml b/lib/kernel/doc/src/inet.xml
index 4c4a5c39c..36a99f7a7 100644
--- a/lib/kernel/doc/src/inet.xml
+++ b/lib/kernel/doc/src/inet.xml
@@ -909,7 +909,7 @@ setcap cap_sys_admin,cap_sys_ptrace,cap_dac_read_search+epi beam.smp</code>
 </item>
 <tag><c>{packet, PacketType}</c>(TCP/IP sockets)</tag>
 <item>
- Defines the type of packets to use for a socket.
+ <marker id="packet"/>Defines the type of packets to use for a socket.
 	 Possible values:
 <taglist>
 <tag><c>raw | 0</c></tag>
-- 
2.12.2

Places

File 0058-kernel-Expand-gen_tcp-close-docs-with-send-text.patch of Package erlang (Revision 46c5166937f7e2f1fa2e44c030dd0337)

Places