You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@apr.apache.org by ge...@everythingsucks.co.uk on 2006/01/01 16:01:05 UTC
Re: Documentation
[Comments in line]
Quoting Paul Querna <ch...@force-elite.com>:
> The web host must be easily moved between servers. Our current
> servers do not run a database for any TLP site.
>
> The web host cannot run anything besides CGI. We only use a CGI for
> the download page. I don't think we want to expand the use of CGI,
> for the sake of the load average of minotaur and ajax.
>
> Our website should be purely static files. This is currently a
> requirement(1) for almost all the TLPs and their websites.
[GC] These are fair, though rather preclusive, points. I'd rather not
enter discussion of what the environmental constraints are at the
moment but instead to explore the Documentation problem further.
> I think better documentation is a good thing. I don't want to stand
> in the way of that. I am not sure I like the PHP method of allowing
> comments. I believe documentation should be authoritative, not
> 'maybe this will work, but try this other way someone mentioned in
> the comments'.
[GC] I belive that, in APR, the only authoritative documentation (i.e.
official, complete and accurate) is the source. This problem is,
of-course, not unique to APR.
Total completeness and accuracy in software documentation is very hard
to achieve but especially in rapidly evolving projects such as APR. So
it becomes a question of acceptability and hence means the quality of
the documentation is subjective.
In my opinion community-driven documentation is one good way of
delivering fast results. What the PHP Group have done is produce a set
of interactive documentation on which their user-base can offer
feedback, corrections and examples - and where other users can find
them without digging around in bugzilla or mail lists.
If, for example, the doxygen API documents and any user-feedback are
treated as two seperate islands then I think we would end up with a
situation like 'maybe this will work, but try this other way someone
mentioned in the comments'. However this is not how it should work,
they should be complementary. It is important that the user-comments
influence the offical documentation (when appropriate).
It is also important that quality-gates are put in place for any user
contributions to ensure that only those which are accurate and
generally use-full are actually published.
In my view this is the, now classic, open-source positive feedback
cycle. Better documentation means wider take-up, wider take-up means
more eyeballs, more eyeballs means more APR contributors both to code
and documentation.
> (1) Okay, so its not written in stone anywhere, but I think there
> would be major resistance to running PHP on the main apache.org
> webserver(s). Maybe we will have more options once FastCGI support
> is in mod_proxy... but not right now.
[GC] Absolutely fair, though in my defence PHP+MySQL was given as an
example. Another example would be doing it all offline and publishing
periodic updates. User comments would simply be written to a text-file
and dealt with later. If/when the time comes that we implement
something like this then we can find an appropriate solution to deal
with these concerns.
Regards
Gerry Calderhead
Re: UPDATE: [Patch] poll/unix/poll.c:apr_pollset_poll()
optimisation
Posted by ge...@everythingsucks.co.uk.
Quoting "Roy T. Fielding" <fi...@gbiv.com>:
> On Jan 4, 2006, at 4:42 PM, gerry@everythingsucks.co.uk wrote:
>
>> Quoting Garrett Rooney <ro...@electricjellyfish.net>:
>>
>>> Um, I don't think that's going to work, rv is the number of
>>> descriptors that hit, there's nothing that says that if N hit it'll be
>>> the first N...
>>
>> That would be true were I comparing I<RV but I'm comapring J<RV :D
>
>>>> - for (i = 0; i < pollset->nelts; i++) {
>>>> + for (i = 0; j < rv; i++) {
>
> I have a vague recollection that there was some reason we couldn't
> trust the return value being equal to the number of ready descriptors
> on some platform, but I have no time to search the archives for why.
> I may be remembering something related to ... er .. that other call
> like poll... hmmm, oh, select. Or maybe I just need more caffeine.
>
> ....Roy
>
You are correct, select() returns the total number of descriptors in
the FDSET rather than those which have had events.
However the patch applies specifically to the poll() implementation for
pollset, select() remains unchanged for that very reason.
Re: UPDATE: [Patch] poll/unix/poll.c:apr_pollset_poll() optimisation
Posted by "Roy T. Fielding" <fi...@gbiv.com>.
On Jan 4, 2006, at 4:42 PM, gerry@everythingsucks.co.uk wrote:
> Quoting Garrett Rooney <ro...@electricjellyfish.net>:
>
>> Um, I don't think that's going to work, rv is the number of
>> descriptors that hit, there's nothing that says that if N hit
>> it'll be
>> the first N...
>
> That would be true were I comparing I<RV but I'm comapring J<RV :D
>>> - for (i = 0; i < pollset->nelts; i++) {
>>> + for (i = 0; j < rv; i++) {
I have a vague recollection that there was some reason we couldn't
trust the return value being equal to the number of ready descriptors
on some platform, but I have no time to search the archives for why.
I may be remembering something related to ... er .. that other call
like poll... hmmm, oh, select. Or maybe I just need more caffeine.
....Roy
Re: UPDATE: [Patch] poll/unix/poll.c:apr_pollset_poll()
optimisation
Posted by ge...@everythingsucks.co.uk.
Quoting Garrett Rooney <ro...@electricjellyfish.net>:
> Um, I don't think that's going to work, rv is the number of
> descriptors that hit, there's nothing that says that if N hit it'll be
> the first N...
That would be true were I comparing I<RV but I'm comapring J<RV :D
> As for the other version of this patch, I'm kind of curious if it's an
> actual improvement. Sure, you can bail early, but at the cost of
> intruducing an extra if into each of the iterations before you bail.
> Is that actually better in the average case?
Yeah I kinda thought the same thing, was bugging me which is why I
revisited it.
G
> On 1/4/06, gerry@everythingsucks.co.uk <ge...@everythingsucks.co.uk> wrote:
>> Greetings,
>>
>> There's a sneakier (and pretty obvious, once you look at it) way of
>> improving this loop which I prefer to my original mail by replacing the
>> for-loop condition.
>>
>> Should be safe: I like poll()... he has an honest face... I don't think
>> he will lie to us about the number of signalled descriptors.
>>
>>
>> --- poll.c 2006/01/02 18:30:27 1.1
>> +++ poll.c 2006/01/05 00:11:36
>> @@ -254,13 +254,13 @@
>> return apr_get_netos_error();
>> }
>> if (rv == 0) {
>> return APR_TIMEUP;
>> }
>> j = 0;
>> - for (i = 0; i < pollset->nelts; i++) {
>> + for (i = 0; j < rv; i++) {
>> if (pollset->pollset[i].revents != 0) {
>> pollset->result_set[j] = pollset->query_set[i];
>> pollset->result_set[j].rtnevents =
>> get_revent(pollset->pollset[i].revents);
>> j++;
>> }
>>
>
> Um, I don't think that's going to work, rv is the number of
> descriptors that hit, there's nothing that says that if N hit it'll be
> the first N...
>
> As for the other version of this patch, I'm kind of curious if it's an
> actual improvement. Sure, you can bail early, but at the cost of
> intruducing an extra if into each of the iterations before you bail.
> Is that actually better in the average case?
>
> -garrett
>
Re: UPDATE: [Patch] poll/unix/poll.c:apr_pollset_poll() optimisation
Posted by Garrett Rooney <ro...@electricjellyfish.net>.
On 1/4/06, gerry@everythingsucks.co.uk <ge...@everythingsucks.co.uk> wrote:
> Greetings,
>
> There's a sneakier (and pretty obvious, once you look at it) way of
> improving this loop which I prefer to my original mail by replacing the
> for-loop condition.
>
> Should be safe: I like poll()... he has an honest face... I don't think
> he will lie to us about the number of signalled descriptors.
>
>
> --- poll.c 2006/01/02 18:30:27 1.1
> +++ poll.c 2006/01/05 00:11:36
> @@ -254,13 +254,13 @@
> return apr_get_netos_error();
> }
> if (rv == 0) {
> return APR_TIMEUP;
> }
> j = 0;
> - for (i = 0; i < pollset->nelts; i++) {
> + for (i = 0; j < rv; i++) {
> if (pollset->pollset[i].revents != 0) {
> pollset->result_set[j] = pollset->query_set[i];
> pollset->result_set[j].rtnevents =
> get_revent(pollset->pollset[i].revents);
> j++;
> }
>
Um, I don't think that's going to work, rv is the number of
descriptors that hit, there's nothing that says that if N hit it'll be
the first N...
As for the other version of this patch, I'm kind of curious if it's an
actual improvement. Sure, you can bail early, but at the cost of
intruducing an extra if into each of the iterations before you bail.
Is that actually better in the average case?
-garrett
UPDATE: [Patch] poll/unix/poll.c:apr_pollset_poll() optimisation
Posted by ge...@everythingsucks.co.uk.
Greetings,
There's a sneakier (and pretty obvious, once you look at it) way of
improving this loop which I prefer to my original mail by replacing the
for-loop condition.
Should be safe: I like poll()... he has an honest face... I don't think
he will lie to us about the number of signalled descriptors.
--- poll.c 2006/01/02 18:30:27 1.1
+++ poll.c 2006/01/05 00:11:36
@@ -254,13 +254,13 @@
return apr_get_netos_error();
}
if (rv == 0) {
return APR_TIMEUP;
}
j = 0;
- for (i = 0; i < pollset->nelts; i++) {
+ for (i = 0; j < rv; i++) {
if (pollset->pollset[i].revents != 0) {
pollset->result_set[j] = pollset->query_set[i];
pollset->result_set[j].rtnevents =
get_revent(pollset->pollset[i].revents);
j++;
}
Cheers
Gerry Calderhead
Quoting gerry@everythingsucks.co.uk:
> Greetings,
>
> Spotted an early-exit optimisation in poll/unix/poll.c:apr_pollset_poll().
>
> We know the number of signalled descriptors, NUM, returned from the
> poll() call so we could bust out of the post-processing loop once
> we've added NUM signalled descriptors to our RESULT_SET.
>
> Cheers
> Gerry Calderhead
>
> [gerry@devbox unix]$ rcsdiff -u6 poll.c
> ===================================================================
> RCS file: RCS/poll.c,v
> retrieving revision 1.1
> diff -u6 -r1.1 poll.c
> --- poll.c 2006/01/02 18:30:27 1.1
> +++ poll.c 2006/01/02 20:16:14
> @@ -259,13 +259,13 @@
> j = 0;
> for (i = 0; i < pollset->nelts; i++) {
> if (pollset->pollset[i].revents != 0) {
> pollset->result_set[j] = pollset->query_set[i];
> pollset->result_set[j].rtnevents =
> get_revent(pollset->pollset[i].revents);
> - j++;
> + if ((++j)==(*num)) break;
> }
> }
> if (descriptors)
> *descriptors = pollset->result_set;
> return APR_SUCCESS;
> }
>
>
[Patch] poll/unix/poll.c:apr_pollset_poll() optimisation
Posted by ge...@everythingsucks.co.uk.
Greetings,
Spotted an early-exit optimisation in poll/unix/poll.c:apr_pollset_poll().
We know the number of signalled descriptors, NUM, returned from the
poll() call so we could bust out of the post-processing loop once we've
added NUM signalled descriptors to our RESULT_SET.
Cheers
Gerry Calderhead
[gerry@devbox unix]$ rcsdiff -u6 poll.c
===================================================================
RCS file: RCS/poll.c,v
retrieving revision 1.1
diff -u6 -r1.1 poll.c
--- poll.c 2006/01/02 18:30:27 1.1
+++ poll.c 2006/01/02 20:16:14
@@ -259,13 +259,13 @@
j = 0;
for (i = 0; i < pollset->nelts; i++) {
if (pollset->pollset[i].revents != 0) {
pollset->result_set[j] = pollset->query_set[i];
pollset->result_set[j].rtnevents =
get_revent(pollset->pollset[i].revents);
- j++;
+ if ((++j)==(*num)) break;
}
}
if (descriptors)
*descriptors = pollset->result_set;
return APR_SUCCESS;
}
Re: Documentation
Posted by Nick Kew <ni...@webthing.com>.
On Sunday 01 January 2006 15:01, gerry@everythingsucks.co.uk wrote:
> Total completeness and accuracy in software documentation is very hard
> to achieve but especially in rapidly evolving projects such as APR. So
> it becomes a question of acceptability and hence means the quality of
> the documentation is subjective.
That seems to be an argument for what has happened in practice:
the API documentation in the header files and Doxygen is complemented
by third-party sources (apachetutor and ariel-networks).
> In my opinion community-driven documentation is one good way of
> delivering fast results. What the PHP Group have done is produce a set
> of interactive documentation on which their user-base can offer
> feedback, corrections and examples - and where other users can find
> them without digging around in bugzilla or mail lists.
FWIW, apachetutor is designed to be a halfway-house between author-
driven and community-driven documentation. The software (which is
lightweight and comprises entirely Apache modules) supports both
multiple authorised authors and anonymous community feedback.
If you're interested in contributing there, I can set up an account for you.
> It is also important that quality-gates are put in place for any user
> contributions to ensure that only those which are accurate and
> generally use-full are actually published.
We manage that in the context of the httpd docs by restricting access
to trusted people (committers). That's probably the best we can reasonably
expect when noone is being paid to review documentation.
> > (1) Okay, so its not written in stone anywhere, but I think there
> > would be major resistance to running PHP on the main apache.org
> > webserver(s). Maybe we will have more options once FastCGI support
> > is in mod_proxy... but not right now.
>
> [GC] Absolutely fair, though in my defence PHP+MySQL was given as an
> example.
Should I throw mod_annot (apachetutor) into the pot at this point?
It's a much lighter-weight solution than PHP+MySQL:-)
--
Nick Kew