diff options
Diffstat (limited to 'erts/doc/src/socket_usage.xml')
| -rw-r--r-- | erts/doc/src/socket_usage.xml | 77 |
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> |