mirror of
https://github.com/moparisthebest/curl
synced 2024-12-22 08:08:50 -05:00
86 lines
4.2 KiB
Groff
86 lines
4.2 KiB
Groff
.\" You can view this file with:
|
|
.\" nroff -man [file]
|
|
.\" $Id$
|
|
.\"
|
|
.TH libcurl-multi 5 "20 March 2001" "libcurl 7.9.5" "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\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.
|
|
|
|
When the easy handle is setup for a transfer, then instead of using
|
|
\fIcurl_easy_perform\fP (as when using the easy interface for transfers), you
|
|
should instead add the easy handle to the multi handle using
|
|
\fIcurl_easy_add_handl\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\fP. Once removed from the multi
|
|
handle, you can again use other easy interface functions like
|
|
curl_easy_perform or whatever you think is necessary.
|
|
|
|
Adding the easy handles to the multi handle does not start any
|
|
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\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\fP like a mad man! \fIcurl_multi_fdset\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.
|
|
|
|
\fIcurl_multi_perform\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\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.
|
|
|
|
When all transfers in the multi stack are done, cleanup the multi handle with
|
|
\fIcurl_multi_cleanup\fP. Be careful and please note that you \fBMUST\fP
|
|
invoke separate \fIcurl_easy_cleanup\fP calls on every single easy handle to
|
|
clean them up properly.
|