Re: [mp2] get_brigade/pass_brigade will continue to return apr_status_t

[Stas Bekman <st...@stason.org>]

Stas Bekman wrote:
> While I'm changing most methods to be perlish, I'm very unsure about
> get_brigade and pass_brigade. That interface is poorely documented on 
> Apache side (read: not documented at all) and it's possible that various 
> status codes will be returned and we simply haven't encountered those 
> cases yet. So I'll make an exception here and keep the methods as they 
> are, even though they aren't perlish.
> 
> Unless someone investigates that case before 2.0 is released, they will 
> stay that way.

I feels like I'm talking to myself, but at least my thoughts will get 
documented for the future references.

So I still decided to try and make get_brigade perlish only to discover that 
it's not possible. Since we need to be able to pass $bb from the caller:

that won't work:

sub in_filter {
     my ($filter, $bb, $mode, $block, $readbytes) = @_;

     $bb = $filter->next->get_brigade($mode, $block, $readbytes);

     return Apache::OK;
}

since it overwrites caller's $bb. Of course we could move the buckets, but 
that's not making things any simpler and certainly not more efficient. So the 
API for get_brigade *must* pass $bb as a reference.

In the future we may add an improvement and allow passing 'my $bb' and 
autovivify bucket brigade behind the scenes in cases where a user manually 
does that.

However while changing the tests I've noticed that we have lots of get/pass 
brigade call which don't check the return values and *we* forget to do that, 
then I won't be surprised if many users will forget too. So I'm going to keep 
the arguments as is, but change the return value to return nothing and throw 
exceptions for both methods.

-- 
__________________________________________________________________
Stas Bekman            JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/     mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org   http://ticketmaster.com

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org

Re: [mp2] get_brigade/pass_brigade will continue to return apr_status_t

[Stas Bekman <st...@stason.org>]

Geoffrey Young wrote:
> 
> Stas Bekman wrote:
> 
> 
>>I feels like I'm talking to myself
> 
> 
> well, I'm listening at least :)  I have just been incredibly busy with other
> things lately.  sorry about that.

No problem, just trying not to drag those things and get the API finished 
asap. I'm double pressed as I have to submit my OSCon tutorial papers in 12 
days and I won't want my tutorial attendees get outdated printouts when I 
present it one month later.

>>Since we don't return anything, but rc, from the get_brigade,
>>pass_brigade and fflush, I think the golden solution is to always return
>>rc, but to croak if there is an error and a user didn't bother to check
>>rc (i.e. calling in the void context).
> 
> 
> that sounds like a really nice idiom for us to follow - if the user
> specifically captures $rc then assume they want to handle it, but croak if
> they don't even check the return code.
> 
> perl++ for letting us know stuff like that in the first place :)

Yeah, I like that too. The only problem is when a user captures $rc, but 
doesn't do anything with it. ;) I found quite a few places in our tests that 
did just that. Now fixed.

But this is not only for lazy users, this is good for everybody. Most of the 
time you really don't need to check for errors, if you know that any will be 
handled for you. The only time when you need to do that if you want to trap 
them and may be do something else instead of failing, or if there is an $rc 
which is not APR::SUCCESS, but still not a failure. e.g. in the case of 
protocol handlers you get APR::EOF at the end of the connection and it's not a 
failure code. So here you want to handle the errors by yourself.

The current tests do both - explicit and implicit error checking.

-- 
__________________________________________________________________
Stas Bekman            JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/     mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org   http://ticketmaster.com

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org

Re: [mp2] get_brigade/pass_brigade will continue to return apr_status_t

[Geoffrey Young <ge...@modperlcookbook.org>]

Stas Bekman wrote:

> I feels like I'm talking to myself

well, I'm listening at least :)  I have just been incredibly busy with other
things lately.  sorry about that.

> Since we don't return anything, but rc, from the get_brigade,
> pass_brigade and fflush, I think the golden solution is to always return
> rc, but to croak if there is an error and a user didn't bother to check
> rc (i.e. calling in the void context).

that sounds like a really nice idiom for us to follow - if the user
specifically captures $rc then assume they want to handle it, but croak if
they don't even check the return code.

perl++ for letting us know stuff like that in the first place :)

--Geoff

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org

Re: [mp2] get_brigade/pass_brigade will continue to return apr_status_t

[Stas Bekman <st...@stason.org>]

Since we don't return anything, but rc, from the get_brigade, pass_brigade and 
fflush, I think the golden solution is to always return rc, but to croak if 
there is an error and a user didn't bother to check rc (i.e. calling in the 
void context).

If you are wondering why I'm bothering to change all these APIs, it's in order 
to make things more perlish. But more important to have as few API functions 
as possible that allow users to write code that doesn't check return values. 
This is in order to make our user support life easier and always croak when 
something is wrong, so users won't submit bug reports, for something that's 
their code's problem. Not needing to check for errors also makes prototyping 
much faster and easier to read.

When saying users I refer to developers who use mod_perl 2.0 API.

-- 
__________________________________________________________________
Stas Bekman            JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/     mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org   http://ticketmaster.com

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org