| .\" You can view this file with: |
| .\" nroff -man [file] |
| .\" $Id$ |
| .\" |
| .TH libcurl-multi 3 "13 Oct 2001" "libcurl 7.10.1" "libcurl multi interface" |
| .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's also the libcurl-the-guide document for a complete tutorial to |
| programming with libcurl and the \fIlibcurl(3)\fP man page for an overview of |
| the libcurl easy interface. |
| |
| All functions in the multi interface are prefixed with curl_multi. |
| .SH "PLEASE NOTICE" |
| The multi interface is a rather new member of the libcurl family. It has not |
| yet been very widely used. It may still be a few more bugs lurking in there |
| than we are used to. That said, it might also just work in every aspect you |
| try it. Please report all bugs and oddities you see. |
| .SH "OBJECTIVES" |
| The multi interface introduces several new abilities that the easy interface |
| refuses to offer. 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 select() on its own file descriptors and curl's |
| file descriptors simultaneous easily. |
| .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. |
| |
| Each single transfer is built up with an easy handle. You must create them, |
| and setup the appropriate options for each easy handle, as outlined in the |
| \fIlibcurl(3)\fP man page, using \fIcurl_easy_setopt(3)\fP. |
| |
| When the easy handle is setup for a transfer, then instead of using |
| \fIcurl_easy_perform(3)\fP (as when using the easy interface for transfers), |
| you should instead add the easy handle to the multi handle using |
| \fIcurl_multi_add_handle(3)\fP. The multi handle is sometimes referred to as a |
| \'multi stack\' because of the fact that it may hold a large amount of easy |
| handles. |
| |
| 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. |
| |
| 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 will then transfer data if there is |
| anything available to transfer. It'll use the callbacks and everything else |
| you have setup in the individual easy handles. It'll transfer data on all |
| current transfers in the multi stack that are ready to transfer anything. It |
| may be all, it may be none. |
| |
| Your application can acquire knowledge from libcurl when it would like to get |
| invoked to transfer data, so that you don't have to busy-loop and call that |
| \fIcurl_multi_perform(3)\fP like crazy. \fIcurl_multi_fdset(3)\fP offers an |
| interface using which you can extract fd_sets 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. 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 |
| successful. One or more of the transfers may have failed. Tracking when this |
| number changes, you know when one or more transfers are done. |
| |
| 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 all transfers in the multi stack are done, cleanup 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 on every single easy handle |
| to clean them up properly. |
| |
| 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). |