httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rici Lake <r...@ricilake.net>
Subject Re: Proposed patch: always cleanup brigades in ap_pass_brigade
Date Tue, 26 Apr 2005 17:05:17 GMT

On 26-Apr-05, at 5:28 AM, Joe Orton wrote:
>
> This is really just a "should we provide extra API guarantees to 
> prevent
> users shooting themselves in the foot" debate, right?  Let's agree to
> disagree :)

Fair enough. I guess where I'm coming from is that I'm a user of the
API, and my feet have been shot at enough times already :)

>> In any event, a draft docstring. This does not reflect my view, and I
>> don't know if there is actually a consensus view, but it may reflect
>> the current state of affairs:
>
> It got linewrapped (format=flowed?) but otherwise I think this looks
> good - thanks a lot.

Sorry about that. The first time I saw RFC 2646, I checked the date to 
see whether it was a prank. Sadly, no -- it's standards track. And the 
problem with standards is that people *will* go and implement them, no 
matter how dumb they might be...

> Final chance for any dissenter to object? Else
> I'll commit this...

My final thoughts: We've agreed, I think, on the following:

1) The caller retains ownership of the brigade. The callee *must not* 
destroy it.

2) The caller has made a contract that every bucket in the brigade will 
remain valid until the callee returns. It does not guarantee anything 
beyond that, so the callee *must* explicitly setaside any buckets it 
wants to retain.

3) The callee may manipulate the contents of the brigade as it sees 
fit, during the span of the call. That is, it may insert and remove 
buckets, pass the brigade to another filter, read buckets (possibly 
morphing the brigade), etc. However, if it removes a bucket, that 
bucket becomes its responsibility.

I hope that's clear from the docstring I wrote.

So the only point of disagreement is the state of the brigade on return.

Number 3 above does not permit any semantics to be attached to the 
state of the brigade on return; any such semantics would have to be a 
private agreement between caller and callee, and the filter mechanism 
does not lend itself to such private agreements because it is not easy 
to guarantee that no other filter intervenes in the filter chain. If 
someone wanted to stack their own filters in this manner, they could 
just call the filter function directly rather than using 
ap_pass_brigade.

So the current state of play is: the callee MAY empty the brigade; the 
caller MUST cleanup the brigade if it wishes to reuse it. This leads to 
precisely the duplication of calls to apr_brigade_cleanup that people 
seem to be objecting to.

Better in that case would be that the callee MUST empty the brigade 
(and, in accordance with (2) and (3) above, either delete or setaside 
the buckets it removes.) In that case, the caller need not cleanup the 
brigade; it is permitted to assume that it is empty on return and need 
not waste cycles on a pointless apr_brigade_cleanup.

If there is any chance of agreement on this, I can produce a modified 
docstring on a moment's notice. :)

Rici


Mime
View raw message