pycurl/doc/curlmultiobject.html

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   3     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   4 <html xmlns="http://www.w3.org/1999/xhtml">
   5 <head>
   6   <title>PycURL: CurlMulti Objects</title>
   7   <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
   8   <meta name="revisit-after" content="30 days" />
   9   <meta name="robots" content="noarchive, index, follow" />
  10 </head>
  11 <body>
  12
  13 <h1>CurlMulti Object</h1>
  14
  15 <p>CurlMulti objects have the following methods: </p>
  16
  17 <dl>
  18 <dt><code>close()</code> -&gt; <em>None</em></dt>
  19 <dd>
  20 <p>Corresponds to
  21 <a href="http://curl.haxx.se/libcurl/c/curl_multi_cleanup.html"><code>curl_multi_cleanup()</code></a> in libcurl.
  22 This method is automatically called by pycurl when a CurlMulti object no
  23 longer has any references to it, but can also be called
  24 explicitly.</p>
  25 </dd>
  26
  27 <dt><code>perform()</code> -&gt; <em>tuple of status and the number of active Curl objects</em></dt>
  28 <dd>
  29 <p>Corresponds to
  30 <a href="http://curl.haxx.se/libcurl/c/curl_multi_perform.html"><code>curl_multi_perform()</code></a> in libcurl.</p>
  31 </dd>
  32
  33 <dt><code> add_handle(</code><em>Curl object</em><code>) </code>-&gt; <em>None</em></dt>
  34 <dd>
  35 <p>Corresponds to
  36 <a href="http://curl.haxx.se/libcurl/c/curl_multi_add_handle.html"><code>curl_multi_add_handle()</code></a> in libcurl.
  37 This method  adds an existing and valid Curl object to the CurlMulti
  38 object.</p>
  39
  40 <p>IMPORTANT NOTE: add_handle does not implicitly add a Python reference
  41 to the Curl object (and thus does not increase the reference count on the Curl
  42 object).</p>
  43 </dd>
  44
  45 <dt><code>remove_handle(</code><em>Curl object</em><code>)</code> -&gt; <em>None</em></dt>
  46 <dd>
  47 <p>Corresponds to
  48 <a href="http://curl.haxx.se/libcurl/c/curl_multi_remove_handle.html"><code>curl_multi_remove_handle()</code></a> in libcurl.
  49 This method removes an existing and valid Curl object from the CurlMulti
  50 object.</p>
  51
  52 <p>IMPORTANT NOTE: remove_handle does not implicitly remove a Python reference
  53 from the Curl object (and thus does not decrease the reference count on the Curl
  54 object).</p>
  55 </dd>
  56
  57 <dt><code>fdset()</code> -&gt;
  58 <em>triple of lists with active file descriptors,
  59 readable,  writeable, exceptions.</em></dt>
  60 <dd>
  61 <p>Corresponds to
  62 <a href="http://curl.haxx.se/libcurl/c/curl_multi_fdset.html"><code>curl_multi_fdset()</code></a> in libcurl.
  63 This method extracts  the file descriptor information from a CurlMulti object.
  64 The returned  lists can be used with the <code>select</code> module to
  65 poll for events.</p>
  66
  67 <p>Example usage:</p>
  68
  69 <pre>
  70 import pycurl
  71 c = pycurl.Curl()
  72 c.setopt(pycurl.URL, "http://curl.haxx.se")
  73 m = pycurl.CurlMulti()
  74 m.add_handle(c)
  75 while 1:
  76     ret, num_handles = m.perform()
  77     if ret != pycurl.E_CALL_MULTI_PERFORM: break
  78 while num_handles:
  79     apply(select.select, m.fdset() + (1,))
  80     while 1:
  81         ret, num_handles = m.perform()
  82         if ret != pycurl.E_CALL_MULTI_PERFORM: break
  83 </pre>
  84 </dd>
  85
  86 <dt><code>select(</code><em>[timeout]</em><code>)</code> -&gt;
  87 <em>number of ready file descriptors or -1 on timeout</em></dt>
  88 <dd>
  89 <p>This is a convenience function which simplifies the combined
  90 use of <code>fdset()</code> and the <code>select</code> module.</p>
  91
  92 <p>Example usage:</p>
  93
  94 <pre>import pycurl
  95 c = pycurl.Curl()
  96 c.setopt(pycurl.URL, "http://curl.haxx.se")
  97 m = pycurl.CurlMulti()
  98 m.add_handle(c)
  99 while 1:
 100     ret, num_handles = m.perform()
 101     if ret != pycurl.E_CALL_MULTI_PERFORM: break
 102 while num_handles:
 103     ret = m.select()
 104     if ret == -1:  continue
 105     while 1:
 106         ret, num_handles = m.perform()
 107         if ret != pycurl.E_CALL_MULTI_PERFORM: break
 108 </pre>
 109 </dd>
 110
 111 <dt><code>info_read(</code><em>[max]</em><code>)</code> -&gt;
 112 <em>numberof queued messages, a list of successful objects, a list of
 113 failed objects</em></dt>
 114 <dd>
 115 <p>Corresponds to the
 116 <a href="http://curl.haxx.se/libcurl/c/curl_multi_info_read.html"><code>curl_multi_info_read()</code></a> function in libcurl.
 117 This method extracts at most <em>max</em> messages
 118 from the multi stack and returns them in two lists. The first
 119 list contains the handles which completed successfully and the second
 120 list contains a tuple <em>&lt;curl object, curl error number, curl
 121 error message&gt;</em> for each failed curl object. The number
 122 of queued messages after this method has been called is also
 123 returned.</p>
 124 </dd>
 125 </dl>
 126
 127 <hr />
 128 <p>
 129   <a href="http://validator.w3.org/check/referer"><img align="right"
 130      src="http://www.w3.org/Icons/valid-xhtml10"
 131      alt="Valid XHTML 1.0!" height="31" width="88" border="0" /></a>
 132   $Id$
 133 </p>
 134
 135 </body>
 136 </html>