doc/tclcurl_multi.n

   1 .\" You can view this file with:
   2 .\" nroff -man [file]
   3 .\" Adapted from libcurl docs by fandom@telefonica.net
   4 .TH TclCurl n "8 September 2008" "TclCurl 7.19.0" "TclCurl Multi Interface"
   5 .SH NAME
   6 TclCurl: - get  a  URL with FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, FILE or LDAP syntax.
   7 .SH SYNOPSIS
   8 .BI "curl::multiinit"
   9 .sp
  10 .IB multiHandle " addhandle"
  11 .sp
  12 .IB multiHandle " removehandle"
  13 .sp
  14 .IB multiHandle " configure"
  15 .sp
  16 .IB multiHandle " perform"
  17 .sp
  18 .IB multiHandle " active"
  19 .sp
  20 .IB multiHandle " getinfo "
  21 .sp
  22 .IB multihandle " cleanup"
  23 .sp
  24 .IB multihandle " auto"
  25 .sp
  26 .BI "curl::multistrerror " errorCode
  27 .sp
  28 .SH DESCRIPTION
  29 TclCurl's multi interface introduces several new abilities that the easy
  30 interface refuses to offer. They are mainly:
  31 .TP
  32 Enable a "pull" interface. The application that uses TclCurl decides where and when to get/send data.
  33 .TP
  34 Enable multiple simultaneous transfers in the same thread without making it complicated for the application.
  35 .TP
  36 Keep Tk GUIs 'alive' while transfers are taking place.
  37
  38 .SH Blocking
  39 A few areas in the code are still using blocking code, even when used from the
  40 multi interface. While we certainly want and intend for these to get fixed in
  41 the future, you should be aware of the following current restrictions:
  42 .RS
  43 .TP 5
  44 .B Name resolves on non-windows unless c-ares is used.
  45 .TP
  46 .B GnuTLS SSL connections.
  47 .TP
  48 .B Active FTP connections.
  49 .TP
  50 .B HTTP proxy CONNECT operations.
  51 .TP
  52 .B TFTP transfers
  53 .TP
  54 .B file:// transfers.
  55 .RE
  56
  57 .SH curl::multiinit
  58 This procedure must be the first one to call, it returns a \fImultiHandle\fP
  59 that you need to use to invoke TclCurl procedures. The init MUST have a
  60 corresponding call to \fIcleanup\fP when the operation is completed.
  61 .sp
  62 .B RETURN VALUE
  63 .sp
  64 .I multiHandle
  65 to use.
  66 .sp
  67 .SH multiHandle addhandle ?easyHandle?
  68 .sp
  69 Each single transfer is built up with an 'easy' handle, the kind we have been
  70 using so far with TclCurl, you must create them and setup the appropriate
  71 options for each of them. Then we add them to the 'multi stack' using the
  72 \fIaddhandle\fP command.
  73
  74 If the easy handle is not set to use a shared or global DNS cache, it will be made
  75 to use the DNS cache that is shared between all easy handles within the multi handle.
  76
  77 When an easy handle has been added to a multi stack, you can not and you must not use
  78 \fIperform\fP on that handle!
  79
  80 .sp
  81 .I "multiHandle"
  82 is the return code from the \fIcurl::multiinit\fP call.
  83 .sp
  84 .B RETURN VALUE
  85 The possible return values are:
  86 .IP -1
  87 Handle added to the multi stack, please call
  88 .I perform
  89 soon
  90 .IP 0
  91 Handle added ok.
  92 .IP 1
  93 Invalid multi handle.
  94 .IP 2
  95 Invalid 'easy' handle. It could mean that it isn't an easy handle at all, or possibly that
  96 the handle already is in used by this or another multi handle.
  97 .IP 3
  98 Out of memory, you should never get this.
  99 .IP 4
 100 You found a bug in TclCurl.
 101 .sp
 102 .SH multiHandle removehandle ?easyHandle?
 103 .sp
 104 When a transfer is done or if we want to stop a transfer before it is completed,
 105 we can use the \fIremovehandle\fP command. Once removed from the multi handle,
 106 we can again use other easy interface functions on it.
 107
 108 Please note that when a single transfer is completed, the easy handle is still
 109 left added to the multi stack. You need to remove it and then close or, possibly,
 110 set new options to it and add it again to the multi handle to start another transfer.
 111
 112 .sp
 113 .B RETURN VALUE
 114 The possible return values are:
 115 .IP 0
 116 Handle removed ok.
 117 .IP 1
 118 Invalid multi handle.
 119 .IP 2
 120 Invalid 'easy' handle.
 121 .IP 3
 122 Out of memory, you should never get this.
 123 .IP 4
 124 You found a bug in TclCurl.
 125 .sp
 126 .SH multiHandle configure
 127 So far the only option is:
 128 .TP
 129 .B -pipelining
 130 Pass a 1 to enable or 0 to disable. Enabling pipelining on a multi handle will
 131 make it attempt to perform HTTP Pipelining as far as possible for transfers using
 132 this handle. This means that if you add a second request that can use an already
 133 existing connection, the second request will be "piped" on the same connection
 134 rather than being executed in parallel.
 135 .TP
 136 .B -maxconnects
 137 Pass a number which will be used as the maximum amount of simultaneously open
 138 connections that TclCurl may cache. Default is 10, and TclCurl will enlarge
 139 the size for each added easy handle to make it fit 4 times the number of added
 140 easy handles.
 141
 142 By setting this option, you can prevent the cache size to grow beyond the limit
 143 set by you. When the cache is full, curl closes the oldest one in the cache to
 144 prevent the number of open connections to increase.
 145
 146 This option is for the multi handle's use only, when using the easy interface you should instead use it's own \fBmaxconnects\fP option.
 147 .sp
 148 .SH multiHandle perform
 149 Adding the easy handles to the multi stack does not start any transfer.
 150 Remember that one of the main ideas with this interface is to let your
 151 application drive. You drive the transfers by invoking
 152 .I perform.
 153 TclCurl will then transfer data if there is anything available to transfer.
 154 It'll use the callbacks and everything else we have setup in the individual
 155 easy handles. It'll transfer data on all current transfers in the multi stack
 156 that are ready to transfer anything. It may be all, it may be none.
 157
 158 When you call \fBperform\fP and the amount of Irunning handles is
 159 changed from the previous call (or is less than the amount of easy handles
 160 you added to the multi handle), you know that there is one or more
 161 transfers less "running". You can then call \fIgetinfo\fP to
 162 get information about each individual completed transfer.
 163 .sp
 164 .B RETURN VALUE
 165 If everything goes well, it returns the number of running handles, '0' if all
 166 are done. In case of error, it will return the error code.
 167 .sp
 168 .SH multiHandle active
 169 In order to know if any of the easy handles are ready to transfer data before
 170 invoking
 171 .I perform
 172 you can use the
 173 .I active
 174 command, it will return the number of transfers currently active.
 175 .sp
 176 .B RETURN VALUE
 177 The number of active transfers or '-1' in case of error.
 178
 179 .SH multiHandle getinfo
 180 This procedure returns very simple information about the transfers, you
 181 can get more detail information using the \fIgetinfo\fP
 182 command on each of the easy handles.
 183
 184 .sp
 185 .B RETURN VALUE
 186 A list with the following elements:
 187 .TP
 188 easyHandle about which the info is about.
 189 .TP
 190 state of the transfer, '1' if it is done.
 191 .TP
 192 exit code of the transfer, '0' if there was no error,...
 193 .TP
 194 Number of messages still in the info queue.
 195 .TP
 196 In case there are no messages in the queue it will return {"" 0 0 0}.
 197
 198 .SH multiHandle cleanup
 199 This procedure must be the last one to call for a multi stack, it is the opposite of the
 200 .I curl::multiinit
 201 procedure and must be called with the same
 202 .I multiHandle
 203 as input as the
 204 .B curl::multiinit
 205 call returned.
 206
 207 .SH multiHandle auto ?-command \fIcommand\fP?
 208 Using this command Tcl's event loop will take care of periodically invoking \fBperform\fP
 209 for you, before using it, you must have already added at least one easy handle to
 210 the multi handle.
 211
 212 The \fBcommand\fP option allows you to specify a command to invoke after all the easy
 213 handles have finished their transfers, even though I say it is an option, the truth is
 214 you must use this command to cleanup all the handles, otherwise the transfered files
 215 may not be complete.
 216
 217 This support is still in a very experimental state, it may still change without warning.
 218 Any and all comments are welcome.
 219
 220 You can find a couple of examples at \fBtests/multi\fP.
 221
 222 .SH curl::multistrerror errorCode
 223 This procedure returns a string describing the error code passed in the argument.
 224
 225 .SH "SEE ALSO"
 226 .I tclcurl, curl.