X-Git-Url: http://git.sven.stormbind.net/?a=blobdiff_plain;f=doc%2Ftclcurl_multi.html;fp=doc%2Ftclcurl_multi.html;h=09c82f6334d35123b14ab24bbf5f10b8b32e9b2b;hb=b0e6fb6e4379fb87fa2854b84a56c5ad49c644da;hp=0000000000000000000000000000000000000000;hpb=c9a5bcd9d76f699909b24e71a2a216d36062ab0b;p=sven%2Ftclcurl.git
diff --git a/doc/tclcurl_multi.html b/doc/tclcurl_multi.html
new file mode 100755
index 0000000..09c82f6
--- /dev/null
+++ b/doc/tclcurl_multi.html
@@ -0,0 +1,319 @@
+Manpage of TclCurl
+
+TclCurl
+Section: TclCurl Multi Interface (n)
Updated: 8 September 2008
+
+
+NAME
+
+TclCurl: - get a URL with FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, FILE or LDAP syntax.
+
+SYNOPSIS
+
+curl::multiinit
+
+
+multiHandle addhandle
+
+
+multiHandle removehandle
+
+
+multiHandle configure
+
+
+multiHandle perform
+
+
+multiHandle active
+
+
+multiHandle getinfo
+
+
+multihandle cleanup
+
+
+multihandle auto
+
+
+curl::multistrerror errorCode
+
+
+
+
DESCRIPTION
+
+TclCurl's multi interface introduces several new abilities that the easy
+interface refuses to offer. They are mainly:
+
+- Enable a "pull" interface. The application that uses TclCurl decides where
+and when to get/send data.
+ - Enable multiple simultaneous transfers in the same thread without making it
+complicated for the application.
+ - Keep Tk GUIs 'alive' while transfers are taking place.
+
+
+
+
+
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:
+
+- Name resolves on non-windows unless c-ares is used.
+
+
- GnuTLS SSL connections.
+
+
- Active FTP connections.
+
+
- HTTP proxy CONNECT operations.
+
+
- SCP and SFTP connections.
+
+
- SFTP transfers.
+
+
- TFTP transfers
+
+
- file:// transfers.
+
+
+
+
+
curl::multiinit
+
+This procedure must be the first one to call, it returns a multiHandle
+that you need to use to invoke TclCurl procedures. The init MUST have a
+corresponding call to cleanup when the operation is completed.
+
+RETURN VALUE
+
+
+multiHandle
+
+to use.
+
+
+
multiHandle addhandle ?easyHandle?
+
+
+Each single transfer is built up with an 'easy' handle, the kind we have been
+using so far with TclCurl, you must create them and setup the appropriate
+options for each of them. Then we add them to the 'multi stack' using the
+addhandle command.
+
+If the easy handle is not set to use a shared or global DNS cache, it will be made
+to use the DNS cache that is shared between all easy handles within the multi handle.
+
+When an easy handle has been added to a multi stack, you can not and you must not use
+perform on that handle!
+
+
+multiHandle
+
+is the return code from the curl::multiinit call.
+
+RETURN VALUE
+
+The possible return values are:
+
+- -1
-
+Handle added to the multi stack, please call
+perform
+
+soon
+
- 0
-
+Handle added ok.
+
- 1
-
+Invalid multi handle.
+
- 2
-
+Invalid 'easy' handle. It could mean that it isn't an easy handle at all, or possibly that
+the handle already is in used by this or another multi handle.
+
- 3
-
+Out of memory, you should never get this.
+
- 4
-
+You found a bug in TclCurl.
+
+
+
+multiHandle removehandle ?easyHandle?
+
+
+When a transfer is done or if we want to stop a transfer before it is completed,
+we can use the removehandle command. Once removed from the multi handle,
+we can again use other easy interface functions on it.
+
+Please note that when a single transfer is completed, the easy handle is still
+left added to the multi stack. You need to remove it and then close or, possibly,
+set new options to it and add it again to the multi handle to start another transfer.
+
+
+RETURN VALUE
+
+The possible return values are:
+
+- 0
-
+Handle removed ok.
+
- 1
-
+Invalid multi handle.
+
- 2
-
+Invalid 'easy' handle.
+
- 3
-
+Out of memory, you should never get this.
+
- 4
-
+You found a bug in TclCurl.
+
+
+
+multiHandle configure
+
+So far the only option is:
+
+- -pipelining
+
+
-
+Pass a 1 to enable or 0 to disable. Enabling pipelining on a multi handle will
+make it attempt to perform HTTP Pipelining as far as possible for transfers using
+this handle. This means that if you add a second request that can use an already
+existing connection, the second request will be "piped" on the same connection
+rather than being executed in parallel.
+
- -maxconnects
+
+
-
+Pass a number which will be used as the maximum amount of simultaneously open
+connections that TclCurl may cache. Default is 10, and TclCurl will enlarge
+the size for each added easy handle to make it fit 4 times the number of added
+easy handles.
+
+By setting this option, you can prevent the cache size to grow beyond the limit
+set by you. When the cache is full, curl closes the oldest one in the cache to
+prevent the number of open connections to increase.
+
+This option is for the multi handle's use only, when using the easy interface you should instead use it's own maxconnects option.
+
+
+
+multiHandle perform
+
+Adding the easy handles to the multi stack 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
+perform.
+
+TclCurl will then transfer data if there is anything available to transfer.
+It'll use the callbacks and everything else we 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.
+
+When you call perform and the amount of Irunning handles is
+changed from the previous call (or is less than the amount of easy handles
+you added to the multi handle), you know that there is one or more
+transfers less "running". You can then call getinfo to
+get information about each individual completed transfer.
+
+RETURN VALUE
+
+If everything goes well, it returns the number of running handles, '0' if all
+are done. In case of error, it will return the error code.
+
+
+
multiHandle active
+
+In order to know if any of the easy handles are ready to transfer data before
+invoking
+perform
+
+you can use the
+active
+
+command, it will return the number of transfers currently active.
+
+RETURN VALUE
+
+The number of active transfers or '-1' in case of error.
+
+
+
multiHandle getinfo
+
+This procedure returns very simple information about the transfers, you
+can get more detail information using the getinfo
+command on each of the easy handles.
+
+
+RETURN VALUE
+
+A list with the following elements:
+
+- easyHandle about which the info is about.
-
+
- state of the transfer, '1' if it is done.
-
+
- exit code of the transfer, '0' if there was no error,...
-
+
- Number of messages still in the info queue.
-
+
- In case there are no messages in the queue it will return {"" 0 0 0}.
-
+
+
+
+multiHandle cleanup
+
+This procedure must be the last one to call for a multi stack, it is the opposite of the
+curl::multiinit
+
+procedure and must be called with the same
+multiHandle
+
+as input as the
+curl::multiinit
+
+call returned.
+
+
+
multiHandle auto ?-command command?
+
+Using this command Tcl's event loop will take care of periodically invoking perform
+for you, before using it, you must have already added at least one easy handle to
+the multi handle.
+
+The command option allows you to specify a command to invoke after all the easy
+handles have finished their transfers, even though I say it is an option, the truth is
+you must use this command to cleanup all the handles, otherwise the transfered files
+may not be complete.
+
+This support is still in a very experimental state, it may still change without warning.
+Any and all comments are welcome.
+
+You can find a couple of examples at tests/multi.
+
+
+
curl::multistrerror errorCode
+
+This procedure returns a string describing the error code passed in the argument.
+
+
+
SEE ALSO
+
+tclcurl, curl.
+
+
+
+
+ Index
+
+- NAME
-
+
- SYNOPSIS
-
+
- DESCRIPTION
-
+
- Blocking
-
+
- curl::multiinit
-
+
- multiHandle addhandle ?easyHandle?
-
+
- multiHandle removehandle ?easyHandle?
-
+
- multiHandle configure
-
+
- multiHandle perform
-
+
- multiHandle active
-
+
- multiHandle getinfo
-
+
- multiHandle cleanup
-
+
- multiHandle auto ?-command command?
-
+
- curl::multistrerror errorCode
-
+
- SEE ALSO
-
+
+
+This document was created by man2html, using the manual pages.
+
+