diff options
Diffstat (limited to 'erts/doc/src')
| -rw-r--r-- | erts/doc/src/socket.xml | 30 | ||||
| -rw-r--r-- | erts/doc/src/socket_usage.xml | 63 |
2 files changed, 78 insertions, 15 deletions
diff --git a/erts/doc/src/socket.xml b/erts/doc/src/socket.xml index f9dd9575f4..48e91e93a7 100644 --- a/erts/doc/src/socket.xml +++ b/erts/doc/src/socket.xml @@ -47,24 +47,40 @@ <seealso marker="#recv_async"><c>recv/3</c></seealso> function with Timeout set to <c>nowait</c> (<c>recv(Sock, 0, nowait)</c>) when there is actually nothing to read, it will return with - <c>{ok, SelectInfo}</c>. When data eventually arrives a 'select' message - will be sent to the caller: + <c>{ok, </c> + <seealso marker="#type-select_info"><c>SelectInfo</c></seealso><c>}</c>. + When data eventually arrives a 'select' message + will be sent to the caller: </p> + <!-- <list type="ordered"> <item><c>{'$socket', Sock, select, Info}</c></item> </list> - The caller can now make another + --> + <taglist> + <!-- NOTE THAT THE EMPTY TAG IS INTENTIONAL --> + <tag></tag> + <item><c>{'$socket', Sock, select, Info}</c></item> + </taglist> + <p>The caller can now make another call to the recv function and now expect data.</p> <p>Note that all other users are <em>locked out</em> until the 'current user' has called the function (recv in this case).</p> <p>Another message the user must be prepared for (when making asynchronous - calls) is the <c>abort</c> message: + calls) is the <c>abort</c> message:</p> + <!-- <list type="ordered"> - <item><c>{'$socket', Sock, abort, Reason}</c></item> + <item><c>{'$socket', Sock, abort, Info}</c></item> </list> - This message indicates + --> + <taglist> + <!-- NOTE THAT THE EMPTY TAG IS INTENTIONAL --> + <tag></tag> + <item><c>{'$socket', Sock, abort, Info}</c></item> + </taglist> + <p>This message indicates that the (asynchronous) operation has been aborted. If, for instance, the socket has been - closed (by another process), <c>Reason</c> will be <c>{Ref, closed}</c>. </p> + closed (by another process), <c>Info</c> will be <c>{Ref, closed}</c>. </p> </note> <note> <p>There is currently <em>no</em> support for Windows. </p> diff --git a/erts/doc/src/socket_usage.xml b/erts/doc/src/socket_usage.xml index fcfe9b54ec..9d8141b822 100644 --- a/erts/doc/src/socket_usage.xml +++ b/erts/doc/src/socket_usage.xml @@ -54,25 +54,72 @@ <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, SelectInfo}</c>. When data eventually arrives a 'select message' - will be sent to the caller: + <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> + <!-- <list type="ordered"> <item><c>{'$socket', Sock, select, Info}</c></item> </list> - The caller can then make another + --> + <taglist> + <!-- NOTE THAT THE EMPTY TAG IS INTENTIONAL --> + <tag></tag> + <item><c>{'$socket', Sock, select, Info}</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>The user must also be prepared to receive an abort message: </p> + <!-- <list type="ordered"> - <item><c>{'$socket', Sock, abort, Reason}</c></item> + <item><c>{'$socket', Sock, abort, Info}</c></item> </list> - If the operation is aborted + --> + <taglist> + <!-- NOTE THAT THE EMPTY TAG IS INTENTIONAL --> + <tag></tag> + <item><c>{'$socket', Sock, 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>Reason</c> part contains the abort reason (in case the socket - has been closed <c>Reason = {Ref, closed}</c>). </p> + The <c>Info</c> part contains the abort reason (in this case that + the socket has been closed <c>Info = {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> + <!-- + <list type="ordered"> + <item> + <c>{'$socket', Socket :: socket(), Tag :: atom(), Info :: term()}</c> + </item> + </list> + --> + <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>reference()</cell> + </row> + <row> + <cell>abort</cell> + <cell>{reference(), Reason :: term()}</cell> + </row> + <tcaption>socket message info value type</tcaption> + </table> + <p>The <c>reference()</c> is the same as was received in the + <seealso marker="socket#type-select_info"><c>SelectInfo</c></seealso>. </p> </section> </section> |