| 1 |
.\" ************************************************************************** |
| 2 |
.\" * _ _ ____ _ |
| 3 |
.\" * Project ___| | | | _ \| | |
| 4 |
.\" * / __| | | | |_) | | |
| 5 |
.\" * | (__| |_| | _ <| |___ |
| 6 |
.\" * \___|\___/|_| \_\_____| |
| 7 |
.\" * |
| 8 |
.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <[email protected]>, et al. |
| 9 |
.\" * |
| 10 |
.\" * This software is licensed as described in the file COPYING, which |
| 11 |
.\" * you should have received as part of this distribution. The terms |
| 12 |
.\" * are also available at https://curl.haxx.se/docs/copyright.html. |
| 13 |
.\" * |
| 14 |
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell |
| 15 |
.\" * copies of the Software, and permit persons to whom the Software is |
| 16 |
.\" * furnished to do so, under the terms of the COPYING file. |
| 17 |
.\" * |
| 18 |
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY |
| 19 |
.\" * KIND, either express or implied. |
| 20 |
.\" * |
| 21 |
.\" ************************************************************************** |
| 22 |
.\" |
| 23 |
.TH libcurl-multi 3 "19 Sep 2014" "libcurl" "libcurl multi interface" |
| 24 |
.SH NAME |
| 25 |
libcurl-multi \- how to use the multi interface |
| 26 |
.SH DESCRIPTION |
| 27 |
This is an overview on how to use the libcurl multi interface in your C |
| 28 |
programs. There are specific man pages for each function mentioned in |
| 29 |
here. There's also the \fIlibcurl-tutorial(3)\fP man page for a complete |
| 30 |
tutorial to programming with libcurl and the \fIlibcurl-easy(3)\fP man page |
| 31 |
for an overview of the libcurl easy interface. |
| 32 |
|
| 33 |
All functions in the multi interface are prefixed with curl_multi. |
| 34 |
.SH "OBJECTIVES" |
| 35 |
The multi interface offers several abilities that the easy interface doesn't. |
| 36 |
They are mainly: |
| 37 |
|
| 38 |
1. Enable a "pull" interface. The application that uses libcurl decides where |
| 39 |
and when to ask libcurl to get/send data. |
| 40 |
|
| 41 |
2. Enable multiple simultaneous transfers in the same thread without making it |
| 42 |
complicated for the application. |
| 43 |
|
| 44 |
3. Enable the application to wait for action on its own file descriptors and |
| 45 |
curl's file descriptors simultaneously. |
| 46 |
|
| 47 |
4. Enable event-based handling and scaling transfers up to and beyond |
| 48 |
thousands of parallel connections. |
| 49 |
.SH "ONE MULTI HANDLE MANY EASY HANDLES" |
| 50 |
To use the multi interface, you must first create a 'multi handle' with |
| 51 |
\fIcurl_multi_init(3)\fP. This handle is then used as input to all further |
| 52 |
curl_multi_* functions. |
| 53 |
|
| 54 |
With a multi handle and the multi interface you can do several simultaneous |
| 55 |
transfers in parallel. Each single transfer is built up around an easy |
| 56 |
handle. You create all the easy handles you need, and setup the appropriate |
| 57 |
options for each easy handle using \fIcurl_easy_setopt(3)\fP. |
| 58 |
|
| 59 |
There are two flavours of the multi interface, the select() oriented one and |
| 60 |
the event based one we call multi_socket. You will benefit from reading |
| 61 |
through the description of both versions to fully understand how they work and |
| 62 |
differentiate. We start out with the select() oriented version. |
| 63 |
|
| 64 |
When an easy handle is setup and ready for transfer, then instead of using |
| 65 |
\fIcurl_easy_perform(3)\fP like when using the easy interface for transfers, |
| 66 |
you should add the easy handle to the multi handle with |
| 67 |
\fIcurl_multi_add_handle(3)\fP. You can add more easy handles to a multi |
| 68 |
handle at any point, even if other transfers are already running. |
| 69 |
|
| 70 |
Should you change your mind, the easy handle is again removed from the multi |
| 71 |
stack using \fIcurl_multi_remove_handle(3)\fP. Once removed from the multi |
| 72 |
handle, you can again use other easy interface functions like |
| 73 |
\fIcurl_easy_perform(3)\fP on the handle or whatever you think is |
| 74 |
necessary. You can remove handles at any point in time during transfers. |
| 75 |
|
| 76 |
Adding the easy handle to the multi handle does not start the transfer. |
| 77 |
Remember that one of the main ideas with this interface is to let your |
| 78 |
application drive. You drive the transfers by invoking |
| 79 |
\fIcurl_multi_perform(3)\fP. libcurl will then transfer data if there is |
| 80 |
anything available to transfer. It'll use the callbacks and everything else |
| 81 |
you have setup in the individual easy handles. It'll transfer data on all |
| 82 |
current transfers in the multi stack that are ready to transfer anything. It |
| 83 |
may be all, it may be none. When there's nothing more to do for now, it |
| 84 |
returns back to the calling application. |
| 85 |
|
| 86 |
Your application extracts info from libcurl about when it would like to get |
| 87 |
invoked to transfer data or do other work. The most convenient way is to use |
| 88 |
\fIcurl_multi_poll(3)\fP that will help you wait until the application should |
| 89 |
call libcurl again. The older API to accomplish the same thing is |
| 90 |
\fIcurl_multi_fdset(3)\fP that extracts fd_sets from libcurl to use in |
| 91 |
select() or poll() calls in order to get to know when the transfers in the |
| 92 |
multi stack might need attention. Both these APIs allow for your program to |
| 93 |
wait for input on your own private file descriptors at the same time |
| 94 |
\fIcurl_multi_timeout(3)\fP also helps you with providing a suitable timeout |
| 95 |
period for your select() calls. |
| 96 |
|
| 97 |
\fIcurl_multi_perform(3)\fP stores the number of still running transfers in |
| 98 |
one of its input arguments, and by reading that you can figure out when all |
| 99 |
the transfers in the multi handles are done. 'done' does not mean |
| 100 |
successful. One or more of the transfers may have failed. |
| 101 |
|
| 102 |
To get information about completed transfers, to figure out success or not and |
| 103 |
similar, \fIcurl_multi_info_read(3)\fP should be called. It can return a |
| 104 |
message about a current or previous transfer. Repeated invokes of the function |
| 105 |
get more messages until the message queue is empty. The information you |
| 106 |
receive there includes an easy handle pointer which you may use to identify |
| 107 |
which easy handle the information regards. |
| 108 |
|
| 109 |
When a single transfer is completed, the easy handle is still left added to |
| 110 |
the multi stack. You need to first remove the easy handle with |
| 111 |
\fIcurl_multi_remove_handle(3)\fP and then close it with |
| 112 |
\fIcurl_easy_cleanup(3)\fP, or possibly set new options to it and add it again |
| 113 |
with \fIcurl_multi_add_handle(3)\fP to start another transfer. |
| 114 |
|
| 115 |
When all transfers in the multi stack are done, close the multi handle with |
| 116 |
\fIcurl_multi_cleanup(3)\fP. Be careful and please note that you \fBMUST\fP |
| 117 |
invoke separate \fIcurl_easy_cleanup(3)\fP calls for every single easy handle |
| 118 |
to clean them up properly. |
| 119 |
|
| 120 |
If you want to re-use an easy handle that was added to the multi handle for |
| 121 |
transfer, you must first remove it from the multi stack and then re-add it |
| 122 |
again (possibly after having altered some options at your own choice). |
| 123 |
.SH "MULTI_SOCKET" |
| 124 |
\fIcurl_multi_socket_action(3)\fP function offers a way for applications to |
| 125 |
not only avoid being forced to use select(), but it also offers a much more |
| 126 |
high-performance API that will make a significant difference for applications |
| 127 |
using large numbers of simultaneous connections. |
| 128 |
|
| 129 |
\fIcurl_multi_socket_action(3)\fP is then used instead of |
| 130 |
\fIcurl_multi_perform(3)\fP. |
| 131 |
|
| 132 |
When using this API, you add easy handles to the multi handle just as with the |
| 133 |
normal multi interface. Then you also set two callbacks with the |
| 134 |
\fICURLMOPT_SOCKETFUNCTION(3)\fP and \fICURLMOPT_TIMERFUNCTION(3)\fP options |
| 135 |
to \fIcurl_multi_setopt(3)\fP. They are two callback functions that libcurl |
| 136 |
will call with information about what sockets to wait for, and for what |
| 137 |
activity, and what the current timeout time is - if that expires libcurl |
| 138 |
should be notified. |
| 139 |
|
| 140 |
The multi_socket API is designed to inform your application about which |
| 141 |
sockets libcurl is currently using and for what activities (read and/or write) |
| 142 |
on those sockets your application is expected to wait for. |
| 143 |
|
| 144 |
Your application must make sure to receive all sockets informed about in the |
| 145 |
\fICURLMOPT_SOCKETFUNCTION(3)\fP callback and make sure it reacts on the given |
| 146 |
activity on them. When a socket has the given activity, you call |
| 147 |
\fIcurl_multi_socket_action(3)\fP specifying which socket and action there |
| 148 |
are. |
| 149 |
|
| 150 |
The \fICURLMOPT_TIMERFUNCTION(3)\fP callback is called to set a timeout. When |
| 151 |
that timeout expires, your application should call the |
| 152 |
\fIcurl_multi_socket_action(3)\fP function saying it was due to a timeout. |
| 153 |
|
| 154 |
This API is typically used with an event-driven underlying functionality (like |
| 155 |
libevent, libev, kqueue, epoll or similar) with which the application |
| 156 |
"subscribes" on socket changes. This allows applications and libcurl to much |
| 157 |
better scale upward and beyond thousands of simultaneous transfers without |
| 158 |
losing performance. |
| 159 |
|
| 160 |
When you've added your initial set of handles, you call |
| 161 |
\fIcurl_multi_socket_action(3)\fP with CURL_SOCKET_TIMEOUT set in the sockfd |
| 162 |
argument, and you'll get callbacks call that sets you up and you then continue |
| 163 |
to call \fIcurl_multi_socket_action(3)\fP accordingly when you get activity on |
| 164 |
the sockets you've been asked to wait on, or if the timeout timer expires. |
| 165 |
|
| 166 |
You can poll \fIcurl_multi_info_read(3)\fP to see if any transfer has |
| 167 |
completed, as it then has a message saying so. |
| 168 |
.SH "BLOCKING" |
| 169 |
A few areas in the code are still using blocking code, even when used from the |
| 170 |
multi interface. While we certainly want and intend for these to get fixed in |
| 171 |
the future, you should be aware of the following current restrictions: |
| 172 |
|
| 173 |
.nf |
| 174 |
- Name resolves unless the c-ares or threaded-resolver backends are used |
| 175 |
- SOCKS proxy handshakes |
| 176 |
- file:// transfers |
| 177 |
- TELNET transfers |
| 178 |
.fi |
| 179 |
.SH "SEE ALSO" |
| 180 |
.BR libcurl-errors "(3), " libcurl-easy "(3), " libcurl "(3) " |