1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
|
<HTML><HEAD><TITLE>Supporting the 'multi' interface'</TITLE>
</HEAD><BODY>
<html><HEAD>
<TITLE>Multi interface thoughts</TITLE>
<LINK REV="made" HREF="mailto:fandom_At_retemail.es">
<META NAME="author" content="Andres Garcia">
<META name="keywords" content="Tcl/Tk Tcl libcurl curl TclCurl download web grabber">
<META name="description" content="TclCurl home page">
</HEAD>
<H1>Multi-interface</H1>
libcurl's multi interface introduces several new abilities that the easy interface
refuses to offer. They are mainly:
<ul>
<li>Enable a "pull" interface. The application that uses libcurl decides where
and when to ask libcurl to get/send data.<br><br>
<li>Enable multiple simultaneous transfers in the same thread without making it
complicated for the application.<br><br>
<li>Enable the application to select() on its own file descriptors and curl's
file descriptors simultaneous easily.<br><br>
</ul>
<p>From TclCurl's point of view, supporting the interface will give us two
main benefits:
<ul>
<li>Simultaneous downloads without using threads.<br><br>
<li>Keeping Tk GUIs 'alive' while transfers are taking place.<br><br>
</ul>
<p>For the time being, if you want to take a look at libcurl's multi-interface you will have to
download the man pages from the <a href="http://curl.haxx.se/cvs.html">cvs</a>.
<H2>Interface proposal</H2>
<p>The following are my first thoughts about how the interface should look like, as
usual I hardly know what I am talking about, so please, feel free to tell me what
I fool I am. (By the way, I am <b>not</b> kidding)
<p>To use the multi interface, we should first first create a 'multi handle' with
<b>curl::multi::init</b>, or maybe <b>curl::multiInit</b>, this procedure will return
the handle to use as input to all further procedures.
<P>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 <b>addHandle</b> command.
<p>When the easy handles are setup for a transfer we get to transfer something with the
<b>perform</b> command.
<P>If we want to stop a transfer before it is completed, we can use the
<b>removeHandle</b> command. Once removed from the multi
handle, we can again use other easy interface functions.
<P>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
<b>perform</b>. 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.
<P>Applications can acquire knowledge from TclCurl when it would like to get
invoked to transfer data, so that you don't have to busy-loop and call that
<b>perform</b> like a mad man! <b>fdset</b> will return the
number of transfers that want to do something at the time. This should make it
easy for our programs to wait for input or perhaps timeout every now and then.
<P>
<b>perform</b> will have to tell us how many transfers are active, so that it
they drop to zero, we will know they are all done. 'done' does not mean successful.
One or more of the transfers may have failed.
<P>
To get information about completed transfers, to figure out success or not and
similar, <b>getinfo</b> 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.
<P>
When all transfers in the multi stack are done, cleanup the multi handle with
<b>cleanup</b> or maybe simply <b>cleanup</b>. Be careful and please note
that you <B>MUST</B> invoke separate <b>cleanup</b> calls on every single easy handle to
clean them up properly.
<P>
<h2>Example</h2>
<p>It may be easier to know what I am talking about with a little example:
<pre>
set multiHandle [curl::multi::init]
set easyHandle1 [curl::init]
set easyHandle2 [curl::init]
$easyHandle1 configure -url http://personal1.iddeo.es/tclcurl/download/tarball/TclCurl-1.0.tar.gz
$easyHandle1 configure -url http://personal1.iddeo.es/tclcurl/english/index.html
$multiHandle addHandle $easyHandle1
$multlHandle addHandle $easyHandle2
for {set running 1} {$running>0} {} {
# Whatever you code should do
set running [$multiHandle perform]
}
$multiHandle cleanup
$easyHandle1 cleanup
$easyHandle2 cleanup
</pre>
<h2>Ramblings</h2>
<p>The example may look quite simple, specially compared to using threads, but it is
still a lot of work if you only want to do a simple transfer while keeping the GUI
responsive, we need something like <b>curl::transfer</b>, a procedure that returns inmediately
and takes care of the transfer on its own.
<br><br>
<p>So, what do <b>you</b> think?
<br><br>
<HR>
<FONT SIZE=-1>
<a href="mailto:fandom_At_retemail.es">Andrés García</a>
</FONT>
</body></html>
|
