- Robert Iakobashvil added curl_multi_socket_action() to libcurl, which is a

  function that deprecates the curl_multi_socket() function. Using the new
  function the application tell libcurl what action that was found in the
  socket that it passes in. This gives a significant performance boost as it
  allows libcurl to avoid a call to poll()/select() for every call to
  curl_multi_socket*().

1 files changed, 30 insertions, 12 deletions

diff --git a/docs/libcurl/curl_multi_socket.3 b/docs/libcurl/curl_multi_socket.3
index 9ad8257f1..3cfd20b40 100644
--- a/docs/libcurl/curl_multi_socket.3
+++ b/docs/libcurl/curl_multi_socket.3
@@ -4,29 +4,40 @@
 .SH NAME
 curl_multi_socket \- reads/writes available data
 .SH SYNOPSIS
+.nf
 #include <curl/curl.h>
 
+CURLMcode curl_multi_socket_action(CURLM * multi_handle, 
+                                   curl_socket_t sockfd, int ev_bitmask,
+                                   int *running_handles);
+
 CURLMcode curl_multi_socket(CURLM * multi_handle, curl_socket_t sockfd,
                             int *running_handles);
 
 CURLMcode curl_multi_socket_all(CURLM *multi_handle,
                                 int *running_handles);
+.fi
 .SH DESCRIPTION
 Alternative versions of \fIcurl_multi_perform(3)\fP that allows the
-application to pass in one of the file descriptors/sockets that have been
-detected to have \&"action" on them and let libcurl perform. This allows
-libcurl to not have to scan through all possible file descriptors to check for
-action. When the application has detected action on a socket handled by
-libcurl, it should call \fIcurl_multi_socket(3)\fP with the \fBsockfd\fP
-argument set to the socket with the action.
+application to pass in the file descriptor/socket that has been detected to
+have \&"action" on it and let libcurl perform. This allows libcurl to not have
+to scan through all possible file descriptors to check for action. When the
+application has detected action on a socket handled by libcurl, it should call
+\fIcurl_multi_socket_action(3)\fP with the \fBsockfd\fP argument set to the
+socket with the action. When the events on a socket are known, they can be
+passed as an events bitmask \fBev_bitmask\fP by first setting \fBev_bitmask\fP
+to 0, and then adding using bitwise OR (|) any combination of events to be
+choosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or CURL_CSELECT_ERR. When the
+events on a socket are unknown, pass 0 instead, and libcurl will test the
+descriptor internally.
 
 At return, the int \fBrunning_handles\fP points to will contain the number of
 still running easy handles within the multi handle. When this number reaches
 zero, all transfers are complete/done. Note that when you call
-\fIcurl_multi_socket(3)\fP on a specific socket and the counter decreases by
-one, it DOES NOT necessarily mean that this exact socket/transfer is the one
-that completed. Use \fIcurl_multi_info_read(3)\fP to figure out which easy
-handle that completed.
+\fIcurl_multi_socket_action(3)\fP on a specific socket and the counter
+decreases by one, it DOES NOT necessarily mean that this exact socket/transfer
+is the one that completed. Use \fIcurl_multi_info_read(3)\fP to figure out
+which easy handle that completed.
 
 The curl_multi_socket functions inform the application about updates in the
 socket (file descriptor) status by doing none, one or multiple calls to the
@@ -44,6 +55,10 @@ wait for socket actions \- at most \- before doing the timeout action: call
 the \fBcurl_multi_socket(3)\fP function with the \fBsockfd\fP argument set to
 CURL_SOCKET_TIMEOUT.
 
+Usage of \fIcurl_multi_socket(3)\fP is depricated, whereas the function is
+equivalent to \fIcurl_multi_socket_action(3)\fP, when \fBev_bitmask\fP is set 
+to 0.
+
 .SH "CALLBACK DETAILS"
 
 The socket \fBcallback\fP function uses a prototype like this
@@ -115,12 +130,15 @@ callback is called.
 
 7. Wait for action on any of libcurl's sockets
 
-8, When action happens, call curl_multi_socket() for the socket(s) that got
+8, When action happens, call curl_multi_socket_action() for the socket(s) that got
 action.
 
 9. Go back to step 6.
 .SH AVAILABILITY
-This function was added in libcurl 7.15.4, although not deemed stable yet.
+This function was added in libcurl 7.15.4, although deemed stablesince 7.16.0.
+
+\fIcurl_multi_socket(3)\fP is deprecated, use
+\fIcurl_multi_socket_action(3)\fP instead!
 .SH "SEE ALSO"
 .BR curl_multi_cleanup "(3), " curl_multi_init "(3), "
 .BR curl_multi_fdset "(3), " curl_multi_info_read "(3)"