diff options
Diffstat (limited to 'docs/libcurl/libcurl-multi.3')
| -rw-r--r-- | docs/libcurl/libcurl-multi.3 | 184 |
1 files changed, 0 insertions, 184 deletions
diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3 deleted file mode 100644 index 8bd893185..000000000 --- a/docs/libcurl/libcurl-multi.3 +++ /dev/null @@ -1,184 +0,0 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * Project ___| | | | _ \| | -.\" * / __| | | | |_) | | -.\" * | (__| |_| | _ <| |___ -.\" * \___|\___/|_| \_\_____| -.\" * -.\" * Copyright (C) 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 -.\" * are also available at https://curl.se/docs/copyright.html. -.\" * -.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell -.\" * copies of the Software, and permit persons to whom the Software is -.\" * furnished to do so, under the terms of the COPYING file. -.\" * -.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY -.\" * KIND, either express or implied. -.\" * -.\" * SPDX-License-Identifier: curl -.\" * -.\" ************************************************************************** -.\" -.TH libcurl-multi 3 "19 Sep 2014" "libcurl" "libcurl" -.SH NAME -libcurl-multi \- how to use the multi interface -.SH DESCRIPTION -This is an overview on how to use the libcurl multi interface in your C -programs. There are specific man pages for each function mentioned in -here. There is also the \fIlibcurl-tutorial(3)\fP man page for a complete -tutorial to programming with libcurl and the \fIlibcurl-easy(3)\fP man page -for an overview of the libcurl easy interface. - -All functions in the multi interface are prefixed with curl_multi. -.SH "OBJECTIVES" -The multi interface offers several abilities that the easy interface does not. -They are mainly: - -1. Enable a "pull" interface. The application that uses libcurl decides where -and when to ask libcurl to get/send data. - -2. Enable multiple simultaneous transfers in the same thread without making it -complicated for the application. - -3. Enable the application to wait for action on its own file descriptors and -curl's file descriptors simultaneously. - -4. Enable event-based handling and scaling transfers up to and beyond -thousands of parallel connections. -.SH "ONE MULTI HANDLE MANY EASY HANDLES" -To use the multi interface, you must first create a 'multi handle' with -\fIcurl_multi_init(3)\fP. This handle is then used as input to all further -curl_multi_* functions. - -With a multi handle and the multi interface you can do several simultaneous -transfers in parallel. Each single transfer is built up around an easy -handle. You create all the easy handles you need, and setup the appropriate -options for each easy handle using \fIcurl_easy_setopt(3)\fP. - -There are two flavors of the multi interface, the select() oriented one and -the event based one we call multi_socket. You benefit from reading through the -description of both versions to fully understand how they work and -differentiate. We start out with the select() oriented version. - -When an easy handle is setup and ready for transfer, then instead of using -\fIcurl_easy_perform(3)\fP like when using the easy interface for transfers, -you should add the easy handle to the multi handle with -\fIcurl_multi_add_handle(3)\fP. You can add more easy handles to a multi -handle at any point, even if other transfers are already running. - -Should you change your mind, the easy handle is again removed from the multi -stack using \fIcurl_multi_remove_handle(3)\fP. Once removed from the multi -handle, you can again use other easy interface functions like -\fIcurl_easy_perform(3)\fP on the handle or whatever you think is -necessary. You can remove handles at any point during transfers. - -Adding the easy handle to the multi handle does not start the transfer. -Remember that one of the main ideas with this interface is to let your -application drive. You drive the transfers by invoking -\fIcurl_multi_perform(3)\fP. libcurl then transfers data if there is anything -available to transfer. It uses the callbacks and everything else you have -setup in the individual easy handles. It transfers data on all current -transfers in the multi stack that are ready to transfer anything. It may be -all, it may be none. When there is nothing more to do for now, it returns back -to the calling application. - -Your application extracts info from libcurl about when it would like to get -invoked to transfer data or do other work. The most convenient way is to use -\fIcurl_multi_poll(3)\fP that helps you wait until the application should call -libcurl again. The older API to accomplish the same thing is -\fIcurl_multi_fdset(3)\fP that extracts \fIfd_sets\fP from libcurl to use in -select() or poll() calls in order to get to know when the transfers in the -multi stack might need attention. Both these APIs allow for your program to -wait for input on your own private file descriptors at the same time. -\fIcurl_multi_timeout(3)\fP also helps you with providing a suitable timeout -period for your select() calls. - -\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 -successful. One or more of the transfers may have failed. - -To get information about completed transfers, to figure out success or not and -similar, \fIcurl_multi_info_read(3)\fP should be called. It can return a -message about a current or previous transfer. Repeated invokes of the function -get more messages until the message queue is empty. The information you -receive there includes an easy handle pointer which you may use to identify -which easy handle the information regards. - -When a single transfer is completed, the easy handle is still left added to -the multi stack. You need to first remove the easy handle with -\fIcurl_multi_remove_handle(3)\fP and then close it with -\fIcurl_easy_cleanup(3)\fP, or possibly set new options to it and add it again -with \fIcurl_multi_add_handle(3)\fP to start another transfer. - -When all transfers in the multi stack are done, close the multi handle with -\fIcurl_multi_cleanup(3)\fP. Be careful and please note that you \fBMUST\fP -invoke separate \fIcurl_easy_cleanup(3)\fP calls for every single easy handle -to clean them up properly. - -If you want to reuse 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" -\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 makes 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 -\fICURLMOPT_SOCKETFUNCTION(3)\fP and \fICURLMOPT_TIMERFUNCTION(3)\fP options -to \fIcurl_multi_setopt(3)\fP. They are two callback functions that libcurl -calls with information about what sockets to wait for, and for what activity, -and what the current timeout time is - if that expires libcurl should be -notified. - -The multi_socket API is 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 make sure to receive all sockets informed about in the -\fICURLMOPT_SOCKETFUNCTION(3)\fP 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 \fICURLMOPT_TIMERFUNCTION(3)\fP 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. - -This API is typically used with an event-driven underlying functionality (like -libevent, libev, kqueue, epoll or similar) with which the application -"subscribes" on socket changes. This allows applications and libcurl to much -better scale upward and beyond thousands of simultaneous transfers without -losing performance. - -When you have added your initial set of handles, you call -\fIcurl_multi_socket_action(3)\fP with CURL_SOCKET_TIMEOUT set in the -\fIsockfd\fP argument, and you get callbacks invoked that set you up and you -then continue to call \fIcurl_multi_socket_action(3)\fP accordingly when you -get activity on the sockets you have been asked to wait on, or if the timeout -timer expires. - -You can poll \fIcurl_multi_info_read(3)\fP to see if any transfer has -completed, as it then has a message saying so. -.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 unless the c-ares or threaded-resolver backends are used - - file:// transfers - - TELNET transfers -.fi -.SH "SEE ALSO" -.BR libcurl-errors (3), -.BR libcurl-easy (3), -.BR libcurl (3) |