API question

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

I want to add a timeout to the public API (I'm adding "get" style
subscription as an alternative to "listen" style)

Opinions, should I:
a) use qpid::sys::Duration as the timeout parameter?
b) use uint64_t nanosecond value?
c) do something else...

Cheers,
Alan.

Re: API question

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

On Mon, 2007-11-05 at 15:37 +0000, Andrew Stitcher wrote:
> On Mon, 2007-11-05 at 10:26 -0500, Alan Conway wrote:
> > I want to add a timeout to the public API (I'm adding "get" style
> > subscription as an alternative to "listen" style)
> > 
> > Opinions, should I:
> > a) use qpid::sys::Duration as the timeout parameter?
> > b) use uint64_t nanosecond value?
> > c) do something else...

Actually, to reply to myself, I guess it's probably best to provide both
a duration and an absolute time version. to give the users a choice.

Andrew

> 
> c) I think it's usually better to specify timeouts in terms of an
> absolute "wait until" time (I know this isn't the common practice).
> 
> The reason is that the if waiting gets interrupted for some reason other
> than timeout or completion (signal for instance) then all you need to do
> to carry on is the same operation again. I suppose I'm saying this
> operation is idempotent.
> 
> If you specify a duration then you need to calculate the absolute
> waiting time internally to do this, or return the remaining time like
> the Linux select does.
> 
> Incidentally this time shouldn't be related to the clock time rather to
> the uptime, just in case someone changes the clock on you (you're
> running NTP that sort of thing).
> 
> Not sure if this helps!
> 
> Andrew
> 

Re: API question

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

On Mon, 2007-11-05 at 17:17 +0000, Andrew Stitcher wrote:
> On Mon, 2007-11-05 at 11:40 -0500, Alan Conway wrote:
> > ...
> > Agreed - but why would we impose that on the user? What additional
> > flexibility would they gain?
> 
> I guess what I'm really saying is that internally you have to do it with
> an absolute time, so you might as well expose that to the user as well
> in case that's how they want to cast their code, so as per my second
> message we should supply *both* options.
> 
> For example if you want to use these timeouts to keep strict
> time/frequency constraints (and our users might as far as we know) it's
> much easier to do it with an absolute time API than a relative one.
> 
That makes sense. You've just given me twice as much API to write :)

Re: API question

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

On Mon, 2007-11-05 at 11:40 -0500, Alan Conway wrote:
> ...
> Agreed - but why would we impose that on the user? What additional
> flexibility would they gain?

I guess what I'm really saying is that internally you have to do it with
an absolute time, so you might as well expose that to the user as well
in case that's how they want to cast their code, so as per my second
message we should supply *both* options.

For example if you want to use these timeouts to keep strict
time/frequency constraints (and our users might as far as we know) it's
much easier to do it with an absolute time API than a relative one.

All you do is keep adding a fixed offset to the previous time to
approximate closely to a fixed frequency. Whereas if you use a relative
and use the same duration each time then your frequency will drift as
you wake up later and later than the desired time.

Does this make sense to you?

BTW I'm not suggesting that you return externally for any other reason
than got message or timeout.

BTW2 this is a major flaw in the epoll() interface compared to the
select() one in that if you get booted out due to an interrupt you have
no way of knowing how much longer you need to wait for, unless you kept
track of the expected absolute timeout time yourself.

Andrew

> 
> Cheers,
> Alan.
> 

Re: API question

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

On Mon, 2007-11-05 at 15:37 +0000, Andrew Stitcher wrote:
> On Mon, 2007-11-05 at 10:26 -0500, Alan Conway wrote:
> > I want to add a timeout to the public API (I'm adding "get" style
> > subscription as an alternative to "listen" style)
> > 
> > Opinions, should I:
> > a) use qpid::sys::Duration as the timeout parameter?
> > b) use uint64_t nanosecond value?
> > c) do something else...
> 
> c) I think it's usually better to specify timeouts in terms of an
> absolute "wait until" time (I know this isn't the common practice).
> 
> The reason is that the if waiting gets interrupted for some reason other
> than timeout or completion (signal for instance) then all you need to do
> to carry on is the same operation again. I suppose I'm saying this
> operation is idempotent.

That is true for low-level condition waits because you need to be able
to capture the lock to check for 'false wakeup' but I don't see the
benefit in a user API. Can you illustrate what you have in mind?

I'm thinking of something along the lines of 
 bool get(Message&, Timeout); // return false if we timed out.
So the user would say:
 if (get(msg, 10secs)) { handle(msg); } else { handle timeout }

What are you proposing?
 while (get(msg, now+10secs)  { what? }

Why would we ever return other than the two defined outcomes: got a
message/did not get a message? How would the user detect that we are in
this third state? And what could they usefully do about it?

> If you specify a duration then you need to calculate the absolute
> waiting time internally to do this, or return the remaining time like
> the Linux select does.

Agreed - but why would we impose that on the user? What additional
flexibility would they gain?

Cheers,
Alan.

Re: API question

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

On Mon, 2007-11-05 at 10:26 -0500, Alan Conway wrote:
> I want to add a timeout to the public API (I'm adding "get" style
> subscription as an alternative to "listen" style)
> 
> Opinions, should I:
> a) use qpid::sys::Duration as the timeout parameter?
> b) use uint64_t nanosecond value?
> c) do something else...

c) I think it's usually better to specify timeouts in terms of an
absolute "wait until" time (I know this isn't the common practice).

The reason is that the if waiting gets interrupted for some reason other
than timeout or completion (signal for instance) then all you need to do
to carry on is the same operation again. I suppose I'm saying this
operation is idempotent.

If you specify a duration then you need to calculate the absolute
waiting time internally to do this, or return the remaining time like
the Linux select does.

Incidentally this time shouldn't be related to the clock time rather to
the uptime, just in case someone changes the clock on you (you're
running NTP that sort of thing).

Not sure if this helps!

Andrew