From bf481cca791033814163806446ea784b5bfd5436 Mon Sep 17 00:00:00 2001 From: Micael Karlberg Date: Wed, 17 Jul 2019 16:52:37 +0200 Subject: [esock|doc] Clarify select info Clarify select info, used in various functions. OTP-15731 --- erts/doc/src/socket.xml | 42 ++++++++++++++++++++++++++++++------------ erts/doc/src/socket_usage.xml | 10 ++++++---- 2 files changed, 36 insertions(+), 16 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/socket.xml b/erts/doc/src/socket.xml index da049b1a7f..2f7ff2fc07 100644 --- a/erts/doc/src/socket.xml +++ b/erts/doc/src/socket.xml @@ -47,14 +47,16 @@ recv/3 function with Timeout set to nowait (recv(Sock, 0, nowait)) when there is actually nothing to read, it will return with - {ok, - SelectInfo}. + {select, + SelectInfo} + (SelectInfo contains the + SelectRef). When data eventually arrives a 'select' message will be sent to the caller:

- {'$socket', socket(), select, select_ref()} + {'$socket', socket(), select, SelectRef}

The caller can now make another call to the recv function and now expect data.

@@ -70,7 +72,7 @@

This message indicates that the (asynchronous) operation has been aborted. If, for instance, the socket has been closed (by another process), - Info will be {select_ref(), closed}.

+ Info will be {SelectRef, closed}.

There is currently no support for Windows.

@@ -338,7 +340,9 @@

In the case when there is no connections waiting, the function will return with the SelectInfo. The caller can then await a select message, {'$socket', Socket, select, Info} (where - Info is the select_ref() from the SelectInfo), + Info is the + ref + field from the SelectInfo), when a client connects (a subsequent call to accept will then return the socket).

@@ -410,7 +414,9 @@ SelectInfo. The caller can then await a select message, {'$socket', Socket, select, Info} (where - Info is the select_ref() from the SelectInfo, + Info is the + ref + field from the SelectInfo, a subsequent call to connect will then establish the connection).

@@ -551,7 +557,9 @@

In the case when there is no data waiting, the function will return with the SelectInfo. The caller can then await a select message, {'$socket', Socket, select, Info} (where - Info is the select_ref() from the SelectInfo), + Info is the + ref + field from the SelectInfo), when data has arrived (a subsequent call to recv will then return the data).

Note that if a length (> 0) is specified, and only part @@ -610,7 +618,9 @@

In the case when there is no data waiting, the function will return with the SelectInfo. The caller can then await a select message, {'$socket', Socket, select, Info} (where - Info is the select_ref() from the SelectInfo), + Info is the + ref + field from the SelectInfo), when data has arrived (a subsequent call to recvfrom will then return the data).

@@ -686,7 +696,9 @@

In the case when there is no data waiting, the function will return with the SelectInfo. The caller can then await a select message, {'$socket', Socket, select, Info} (where - Info is the select_ref() from the SelectInfo), + Info is the + ref + field from the SelectInfo), when data has arrived (a subsequent call to recvmsg will then return the data).

@@ -714,7 +726,9 @@ the function will return with the SelectInfo. The caller can then await a select message, {'$socket', Socket, select, Info} - (where Info is the select_ref() from the + (where Info is the + ref + field from the SelectInfo), when there is room for more data (a subsequent call to send will then send the data).

Note that if not all the data was sent, the function will return @@ -772,7 +786,9 @@ the function will return with the SelectInfo. The caller can then await a select message, {'$socket', Socket, select, Info} - (where Info is the select_ref() from the + (where Info is the + ref + field from the SelectInfo), when there is room for more data (a subsequent call to sendmsg will then send the data).

@@ -800,7 +816,9 @@ the function will return with the SelectInfo. The caller can then await a select message, {'$socket', Socket, select, Info} - (where Info is the select_ref() from the + (where Info is the + ref + field from the SelectInfo), when there is room for more data (a subsequent call to sendto will then send the data).

diff --git a/erts/doc/src/socket_usage.xml b/erts/doc/src/socket_usage.xml index 7e65bcbf70..b20b8b7730 100644 --- a/erts/doc/src/socket_usage.xml +++ b/erts/doc/src/socket_usage.xml @@ -56,14 +56,16 @@ function with Timeout set to nowait (i.e. recv(Sock, 0, nowait)) when there is actually nothing to read, it will return with - {ok, - SelectInfo}. + {select, + SelectInfo} + (SelectInfo contains the + SelectRef). When data eventually arrives a 'select message' will be sent to the caller:

- {'$socket', socket(), select, select_ref()} + {'$socket', socket(), select, SelectRef}

The caller can then make another call to the recv function and now expect data.

@@ -81,7 +83,7 @@

If the operation is aborted for whatever reason (e.g. if the socket is closed "by someone else"). The Info part contains the abort reason (in this case that - the socket has been closed Info = {select_ref(), closed}).

+ the socket has been closed Info = {SelectRef, closed}).

Note that all other users are locked out until the 'current user' has called the function (recv in this case). So either immediately call the function or -- cgit v1.2.3 From 4309c7b482493d522cb549de85613a0bd840bd30 Mon Sep 17 00:00:00 2001 From: Micael Karlberg Date: Wed, 17 Jul 2019 18:49:03 +0200 Subject: [esock|doc] *May* require admin capability --- erts/doc/src/socket_usage.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'erts/doc') diff --git a/erts/doc/src/socket_usage.xml b/erts/doc/src/socket_usage.xml index b20b8b7730..3d6a961417 100644 --- a/erts/doc/src/socket_usage.xml +++ b/erts/doc/src/socket_usage.xml @@ -224,7 +224,7 @@ integer() yes yes - requires admin capability + may require admin capability domain -- cgit v1.2.3