aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc/src/socket_usage.xml
diff options
context:
space:
mode:
Diffstat (limited to 'erts/doc/src/socket_usage.xml')
-rw-r--r--erts/doc/src/socket_usage.xml77
1 files changed, 75 insertions, 2 deletions
diff --git a/erts/doc/src/socket_usage.xml b/erts/doc/src/socket_usage.xml
index e0f006e618..7e65bcbf70 100644
--- a/erts/doc/src/socket_usage.xml
+++ b/erts/doc/src/socket_usage.xml
@@ -34,11 +34,84 @@
<title>Introduction</title>
<p>The socket interface (module) is basically an "thin" layer on top of
the OS socket interface. It is assumed that, unless you have special needs,
- gen_[tcp|udp|sctp] should be sufficent. </p>
+ gen_[tcp|udp|sctp] should be sufficent (when they become available). </p>
<p>Note that just because we have a documented and described option,
it does <em>not</em> mean that the OS supports it. So its recommended
that the user reads the platform specific documentation for the
option used. </p>
+ <section>
+ <title>Asynchronous calls</title>
+ <p>Some functions allow for an <i>asynchronous</i> call
+ (<seealso marker="socket#accept_async"><c>accept/2</c></seealso>,
+ <seealso marker="socket#connect_async"><c>connect/3</c></seealso>,
+ <seealso marker="socket#recv_async"><c>recv/3,4</c></seealso>,
+ <seealso marker="socket#recvfrom_async"><c>recvfrom/3,4</c></seealso>,
+ <seealso marker="socket#recvmsg_async"><c>recvmsg/2,3,5</c></seealso>,
+ <seealso marker="socket#send_async"><c>send/3,4</c></seealso>,
+ <seealso marker="socket#sendmsg_async"><c>sendmsg/3,4</c></seealso> and
+ <seealso marker="socket#sendto_async"><c>sendto/4,5</c></seealso>).
+ This is achieved by setting the <c>Timeout</c> argument to
+ <c>nowait</c>. For instance, if calling the
+ <seealso marker="socket#recv_async"><c>recv/3</c></seealso>
+ function with Timeout set to <c>nowait</c> (i.e.
+ <c>recv(Sock, 0, nowait)</c>)
+ when there is actually nothing to read, it will return with
+ <c>{ok, </c>
+ <seealso marker="socket#type-select_info"><c>SelectInfo</c></seealso><c>}</c>.
+ When data eventually arrives a 'select message'
+ will be sent to the caller:</p>
+ <taglist>
+ <!-- NOTE THAT THE EMPTY TAG IS INTENTIONAL -->
+ <tag></tag>
+ <item><c>{'$socket', socket(), select, select_ref()}</c></item>
+ </taglist>
+ <p>The caller can then make another
+ call to the recv function and now expect data.</p>
+ <p>The user must also be prepared to receive an abort message: </p>
+ <!--
+ <list type="ordered">
+ <item><c>{'$socket', Sock, abort, Info}</c></item>
+ </list>
+ -->
+ <taglist>
+ <!-- NOTE THAT THE EMPTY TAG IS INTENTIONAL -->
+ <tag></tag>
+ <item><c>{'$socket', socket(), abort, Info}</c></item>
+ </taglist>
+ <p>If the operation is aborted
+ for whatever reason (e.g. if the socket is closed "by someone else").
+ The <c>Info</c> part contains the abort reason (in this case that
+ the socket has been closed <c>Info = {select_ref(), closed}</c>). </p>
+ <p>Note that all other users are <em>locked out</em> until the
+ 'current user' has called the function (recv in this case). So either
+ immediately call the function or
+ <seealso marker="socket#cancel/2"><c>cancel</c></seealso>. </p>
+
+ <p>The general form of the 'socket' message is: </p>
+ <taglist>
+ <!-- NOTE THAT THE EMPTY TAG IS INTENTIONAL -->
+ <tag></tag>
+ <item><c>{'$socket', Sock :: socket(), Tag :: atom(), Info :: term()}</c></item>
+ </taglist>
+ <p>Where the format of <c>Info</c> is a function of <c>Tag</c>:</p>
+ <table>
+ <row>
+ <cell><em>Tag</em></cell>
+ <cell><em>Info value type</em></cell>
+ </row>
+ <row>
+ <cell>select</cell>
+ <cell>select_ref()</cell>
+ </row>
+ <row>
+ <cell>abort</cell>
+ <cell>{select_ref(), Reason :: term()}</cell>
+ </row>
+ <tcaption>socket message info value type</tcaption>
+ </table>
+ <p>The <c>select_ref()</c> is the same as was received in the
+ <seealso marker="socket#type-select_info"><c>SelectInfo</c></seealso>. </p>
+ </section>
</section>
<section>
@@ -205,7 +278,7 @@
<cell>protocol()</cell>
<cell>no</cell>
<cell>yes</cell>
- <cell>none</cell>
+ <cell><em>Not</em> on (some) Darwin (for instance)</cell>
</row>
<row>
<cell>rcvbuf</cell>