multi docs: extended the multi_socket API description

docs/libcurl/libcurl-multi.3

@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2010, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -118,13 +118,32 @@ If you want to re-use an easy handle that was added to the multi handle for
 transfer, you must first remove it from the multi stack and then re-add it
 again (possibly after having altered some options at your own choice).
 .SH "MULTI_SOCKET"
-Since 7.16.0, the \fIcurl_multi_socket_action(3)\fP function offers a way for
-applications to not only avoid being forced to use select(), but it also
-offers a much more high-performance API that will make a significant
-difference for applications using large numbers of simultaneous connections.
-
-\fIcurl_multi_socket_action(3)\fP is then used
-instead of \fIcurl_multi_perform(3)\fP.
+\fIcurl_multi_socket_action(3)\fP function offers a way for applications to
+not only avoid being forced to use select(), but it also offers a much more
+high-performance API that will make a significant difference for applications
+using large numbers of simultaneous connections.
+
+\fIcurl_multi_socket_action(3)\fP is then used instead of
+\fIcurl_multi_perform(3)\fP.
+
+When using this API, you add easy handles to the multi handle just as with the
+normal multi interface. Then you also set two callbacks with the
+CURLMOPT_SOCKETFUNCTION and CURLMOPT_TIMERFUNCTION options to
+\fIcurl_multi_setopt(3)\fP.
+
+The API is then designed to inform your application about which sockets
+libcurl is currently using and for what activities (read and/or write) on
+those sockets your application is expected to wait for.
+
+Your application must then make sure to receive all sockets informed about in
+the CURLMOPT_SOCKETFUNCTION callback and make sure it reacts on the given
+activity on them. When a socket has the given activity, you call
+\fIcurl_multi_socket_action(3)\fP specifying which socket and action there
+are.
+
+The CURLMOPT_TIMERFUNCTION callback is called to set a timeout. When that
+timeout expires, your application should call the
+\fIcurl_multi_socket_action(3)\fP function saying it was due to a timeout.
 .SH "BLOCKING"
 A few areas in the code are still using blocking code, even when used from the
 multi interface. While we certainly want and intend for these to get fixed in