File 1407-kernel-gen-udp-socket-doc-Add-preliminary-... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 1407-kernel-gen-udp-socket-doc-Add-preliminary-documentat.patch of Package erlang (Revision 1cbc14a9258a28addda6173b430c4a37)

Currently displaying revision 1cbc14a9258a28addda6173b430c4a37 , Show latest

From e5d35e2a12efae42bdab5155fb220f81d7f53554 Mon Sep 17 00:00:00 2001
From: Micael Karlberg <bmk@erlang.org>
Date: Thu, 15 Jul 2021 15:15:48 +0200
Subject: [PATCH 07/12] [kernel|gen-udp-socket|doc] Add preliminary
 documentation

Add note about 'inet-backend' and the currently only
difference to "standard" (=port) gen_udp.

OTP-17410
---
 lib/kernel/doc/src/gen_udp.xml | 44 +++++++++++++++++++++++++++++++++-
 lib/kernel/doc/src/inet.xml    |  4 ++++
 lib/kernel/src/gen_udp.erl     | 23 +++++++++---------
 3 files changed, 59 insertions(+), 12 deletions(-)

diff --git a/lib/kernel/doc/src/gen_udp.xml b/lib/kernel/doc/src/gen_udp.xml
index ff65d30cb9..ff11971e9f 100644
--- a/lib/kernel/doc/src/gen_udp.xml
+++ b/lib/kernel/doc/src/gen_udp.xml
@@ -4,7 +4,7 @@
 <erlref>
 <header>
 <copyright>
- <year>1997</year><year>2020</year>
+ <year>1997</year><year>2021</year>
 <holder>Ericsson AB. All Rights Reserved.</holder>
 </copyright>
 <legalnotice>
@@ -33,6 +33,45 @@
 <description>
 This module provides functions for communicating
 with sockets using the UDP protocol.
+
+ <note>
+ 
+ Functions that create sockets can take an optional option;
+ <c>{inet_backend,&nbsp;Backend}</c> that, if specified,
+ has to be the first option. This selects
+ the implementation backend towards the platform's socket API.
+ 
+ 
+ This is a temporary option
+ that will be ignored in a future release.
+ 
+ 
+ The default is <c>Backend&nbsp;=&nbsp;inet</c>
+ that selects the traditional <c>inet_drv.c</c> driver.
+ The other choice is <c>Backend&nbsp;=&nbsp;socket</c>
+ that selects the new <seeerl marker="socket"><c>socket</c></seeerl>
+ module and its NIF implementation.
+ 
+ 
+ The system default can be changed when the node is started
+ with the application <c>kernel</c>'s configuration variable
+ <c>inet_backend</c>.
+ 
+ For <c>gen_udp</c> with <c>inet_backend = socket</c> we have tried
+ to be as "compatible" as possible which has sometimes been impossible.
+ Here is a list of cases when the behaviour of inet-backend
+ <c>inet</c> (default) and <c>socket</c> are different: 
+ <list type="bulleted">
+	<item>
+	 
+	 The option
+	 <seeerl marker="inet#option-read_packets">read_packets</seeerl>
+	 is currently ignored.
+	 
+	</item>
+ </list>
+ </note>
+
 </description>
 
 <datatypes>
@@ -42,6 +81,9 @@
 <datatype>
 <name name="option_name"/>
 </datatype>
+ <datatype>
+ <name name="open_option"/>
+ </datatype>
 <datatype>
 <name>socket()</name>
 <desc>
diff --git a/lib/kernel/doc/src/inet.xml b/lib/kernel/doc/src/inet.xml
index 7d38e39ae1..ed21bac53a 100644
--- a/lib/kernel/doc/src/inet.xml
+++ b/lib/kernel/doc/src/inet.xml
@@ -985,6 +985,7 @@ get_tcpi_sacked(Sock) ->
 mode with values of <c>N</c> appropriate for the application
 provides flow control. The other side cannot send
 faster than the receiver can read.
+ <marker id="option-broadcast"></marker>
 </item>
 <tag><c>{broadcast, Boolean}</c> (UDP sockets)</tag>
 <item>
@@ -1393,6 +1394,7 @@ setcap cap_sys_admin,cap_sys_ptrace,cap_dac_read_search+epi beam.smp</code>
 	 option <c>packet_size</c> also guarantees that lines up to the
 	 indicated length are accepted and not considered invalid
 	 because of internal buffer limitations.
+ <marker id="option-line_delimiter"></marker>
 </item>
 <tag><c>{line_delimiter, Char}</c>(TCP/IP sockets)</tag>
 <item>
@@ -1402,6 +1404,7 @@ setcap cap_sys_admin,cap_sys_ptrace,cap_dac_read_search+epi beam.smp</code>
 <tag><c>{raw, Protocol, OptionNum, ValueBin}</c></tag>
 <item>
 See below.
+ <marker id="option-read_packets"></marker>
 </item>
 <tag><c>{read_packets, Integer}</c>(UDP sockets)</tag>
 <item>
@@ -1413,6 +1416,7 @@ setcap cap_sys_admin,cap_sys_ptrace,cap_dac_read_search+epi beam.smp</code>
 Defaults to <c>5</c>. If this parameter is set too
 high, the system can become unresponsive because of
 UDP packet flooding.
+ <marker id="option-recbuf"></marker>
 </item>
 <tag><c>{recbuf, Size}</c></tag>
 <item>
diff --git a/lib/kernel/src/gen_udp.erl b/lib/kernel/src/gen_udp.erl
index 06f92f1ba0..3de95bcb72 100644
--- a/lib/kernel/src/gen_udp.erl
+++ b/lib/kernel/src/gen_udp.erl
@@ -92,9 +92,18 @@
 pktoptions |
 	ipv6_v6only.
 
+-type open_option() :: {ip, inet:socket_address()}
+ | {fd, non_neg_integer()}
+ | {ifaddr, inet:socket_address()}
+ | inet:address_family()
+ | {port, inet:port_number()}
+ | {netns, file:filename_all()}
+ | {bind_to_device, binary()}
+ | option().
+
 -type socket() :: inet:socket().
 
--export_type([option/0, option_name/0, socket/0]).
+-export_type([option/0, open_option/0, option_name/0, socket/0]).
 
 
 %% -- open ------------------------------------------------------------------
@@ -108,16 +117,8 @@ open(Port) ->
 open(Port, []).
 
 -spec open(Port, Opts) -> {ok, Socket} | {error, Reason} when
- Port :: inet:port_number(),
- Opts :: [Option],
- Option :: {ip, inet:socket_address()}
- | {fd, non_neg_integer()}
- | {ifaddr, inet:socket_address()}
- | inet:address_family()
- | {port, inet:port_number()}
- | {netns, file:filename_all()}
- | {bind_to_device, binary()}
- | option(),
+ Port :: inet:port_number(),
+ Opts :: [inet:inet_backend() | open_option()],
 Socket :: socket(),
 Reason :: system_limit | inet:posix().
 
-- 
2.31.1

Places

File 1407-kernel-gen-udp-socket-doc-Add-preliminary-documentat.patch of Package erlang (Revision 1cbc14a9258a28addda6173b430c4a37)

Places