On Fri, 29 May 2009, Massimo Lombardo wrote:

> I was reading curl_multi_init documentation on php.net [1] when a comment by
> some anonymous (but let's call him "Eddie", ok?) guy [2] kept my attention.

Welcome to the area between two chairs. The chairs being PHP and libcurl and
the area in between called (by me) PHP/CURL.

Neither the cURL project nor the PHP gives this binding the amount of love it
needs, so it lacks. You found one point that shows.

> Eddie basically says that using a while loop/curl_multi_exec combo should be
> considered deprecated, and that the curl_multi_select/curl_multi_exec combo
> should be the preferred one instead.

Eddie is right. A busy-loop is never a good idea. curl_multi_select+
curl_multi_exec is meant to fix that.

> - curl_multi_select documentation page on php.net [3] can be quite
> safely declared empty (doh!);

This is the PHP team's docs. I'm quite sure they will appreciate help though.

> - curl_multi_fdset man page on curl.haxx.se [4] does not provide any
> example nor any relevant information on usage (doh!);

Uh. You're talking about docs for the libcurl C API. In what wat is the
provided documentation not enough to make C coders understand what this
function is good for and how to use it? We also provide a tutorial like docs
for the multi interface (online here:
http://curl.haxx.se/libcurl/c/libcurl-multi.html) that describes how the
functions are used together.

I protest against you calling this a "doh" in any sense from a libcurl hacker
and user's perspective. From a PHP/CURL user's angle perhaps, but this docs is
not meant for those.

> - the "multi" example published at [5] uses the while
> loop/curl_multi_exec combo too (doh!).

If anyone provides a better example, I'll happily replace what we show there.

> - curl_multi_perform man page on curl.haxx.se, in the "Typical Usage"
> section, clearly states:
>
> "Most applications will use curl_multi_fdset(3) to get the multi_handle's
> file descriptors, then it'll wait for action on them using select(3) and as
> soon as one or more of them are ready, curl_multi_perform(3) gets called"
>
> but, again, nothing of such appears at [5]... (doh!)

And now you're again mixing APIs. That's the C API docs while [5] is PHP. I'm
a libcurl hacker and I wrote that section of the docs, while I'm not very much
into the details of the PHP/CURL binding so I didn't write [5].

And again: nobody provided me with a better or alternative example for [5].

> (Where I live, we use to call four dohs in a row an epic fail, but being
> cURL such popular and powerful, I'll call it an epic fail of an hero... :-P)

I agree completely. I find it fascinating that such a well-used and widely
known PHP extension as the PHP/CURL one has such bad docs and that so very few
people contribute fixes and/or documentation improvements for it back to the
PHP team.

Stop waiting. Fix the problems and post your patches.

> So my question is: is the while loop/curl_multi_exec combo the unique
> approach a PHP developer should use

That's an approach that will keep the code busy-looping like mad until all
transfers are complete.

> If Eddie was right, how should we use curl_multi_select?

He is right but I don't know how to use that function.

-- 
  / daniel.haxx.se
_______________________________________________
http://cool.haxx.se/cgi-bin/mailman/listinfo/curl-and-php