C++: API preference question - fallible queue APIs.

[Alan Conway <ac...@redhat.com>]

I can never make up my mind about which option to choose of the
following APIs:

Message get(Timeout); // return Message::none if we timed out.
bool get(Timeout, Message&); // Return true if we got a message

I sorta prefer the former but the latter makes it harder to
invadvertently ignore the possibility of timeout.

I don't like this one:
Message get(Timeout); // throw if timeout

because if you provide a get API with a timeout, that implies that
timing out is an expected possible outcome and throw is inappropriate.

I've no problem with

Message get(); // throw if timeout or unavailable.

Because in this case the user has no reason to expect a timeout so
exception is appropriate.

Cheers,
Alan.

Re: C++: API preference question - fallible queue APIs.

[Andrew Stitcher <as...@redhat.com>]

On Mon, 2007-11-05 at 11:16 -0500, Alan Conway wrote:
> I can never make up my mind about which option to choose of the
> following APIs:
> 
> Message get(Timeout); // return Message::none if we timed out.
> bool get(Timeout, Message&); // Return true if we got a message

I think that APIs with an INFINITE default are more usable:

Message get(Timeout = INFINITE) or
bool get(Message&, Timeout = INFINITE)

would be better IMO (obviously you could have 2 oveloads to the same
effect).

> 
> I sorta prefer the former but the latter makes it harder to
> invadvertently ignore the possibility of timeout.

Do you intend that there has to be a timeout then?

> 
> I don't like this one:
> Message get(Timeout); // throw if timeout
> 
> because if you provide a get API with a timeout, that implies that
> timing out is an expected possible outcome and throw is inappropriate.

I agree: if timeout is a parameter, it's expected hence throwing an
exception isn't appropriate as it's not an exceptional case.

> 
> I've no problem with
> 
> Message get(); // throw if timeout or unavailable.
> 
> Because in this case the user has no reason to expect a timeout so
> exception is appropriate.

I'm not sure here, as if you think this is meant to be an INFINITE
timeout, then you should only throw in the presence of some error
condition which would be the case above as well.

Andrew