diff options
Diffstat (limited to 'docs/libcurl/libcurl-multi.3')
| -rw-r--r-- | docs/libcurl/libcurl-multi.3 | 47 |
1 files changed, 28 insertions, 19 deletions
diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 index d84bafcad..2af029961 100644 --- a/docs/libcurl/libcurl-multi.3 +++ b/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 @@ -82,14 +82,6 @@ might need attention. This also makes it very easy for your program to wait for input on your own private file descriptors at the same time or perhaps timeout every now and then, should you want that. -A little note here about the return codes from the multi functions, and -especially the \fIcurl_multi_perform(3)\fP: if you receive -\fICURLM_CALL_MULTI_PERFORM\fP, this basically means that you should call -\fIcurl_multi_perform(3)\fP again, before you select() on more actions. You -don't have to do it immediately, but the return code means that libcurl may -have more data available to return or that there may be more data to send off -before it is "satisfied". - \fIcurl_multi_perform(3)\fP stores the number of still running transfers in one of its input arguments, and by reading that you can figure out when all the transfers in the multi handles are done. 'done' does not mean @@ -118,23 +110,40 @@ 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 the future, you should be aware of the following current restrictions: .nf - - Name resolves on non-windows unless c-ares is used - - GnuTLS SSL connections + - Name resolves unless the c-ares or threaded-resolver backends are used - NSS SSL connections - - Active FTP connections - HTTP proxy CONNECT operations - SOCKS proxy handshakes - file:// transfers |