142 lines
7.1 KiB
Groff
142 lines
7.1 KiB
Groff
.\" **************************************************************************
|
|
.\" * _ _ ____ _
|
|
.\" * Project ___| | | | _ \| |
|
|
.\" * / __| | | | |_) | |
|
|
.\" * | (__| |_| | _ <| |___
|
|
.\" * \___|\___/|_| \_\_____|
|
|
.\" *
|
|
.\" * Copyright (C) 1998 - 2007, 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 http://curl.haxx.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.
|
|
.\" *
|
|
.\" * $Id$
|
|
.\" **************************************************************************
|
|
.\"
|
|
.TH libcurl-multi 3 "3 Feb 2007" "libcurl 7.16.0" "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 \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 doesn't.
|
|
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 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 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, 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).
|
|
.SH "MULTI_SOCKET"
|
|
Since 7.16.0, the \fIcurl_multi_socket(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-performing API that will make a significant difference
|
|
for applications using large numbers of simultaneous connections.
|
|
|
|
\fIcurl_multi_socket(3)\fP (and \fIcurl_multi_socket_all(3)\fP) is then used
|
|
instead of \fIcurl_multi_perform(3)\fP.
|
|
.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
|
|
- Active FTP connections
|
|
- HTTP proxy CONNECT operations
|
|
- TFTP transfers
|
|
- file:// transfers
|
|
.fi
|