At 01:25 PM 7/14/2002, Ryan Bloom wrote:
My biggest problem is that this is just getting more and more complex, and the conversation is almost impossible to follow. To the best of my knowledge (from trying to follow the conversation), at this point, we are talking about:
Apr_busec_time_t and apr_busec_span_t
As Brian pointed out ... that is option #3, which trails option #2 by one vote.
Instead, our current direction is simply
apr_utime_t and apr_uspan_t
[or apr_utimediff_t, or apr_utimespan_t, depending on which ends up being easier to read and recognize. interval always struck me as awkward ;-]
Of course these are busecs, but prevailing sentiment says we don't include any sort of busec designation the time name.
Now that I've reflected, simply 'utime' introduces two new points of confusion that will confront new users:
1. utime == unsigned time? (u as unsigned prefix) 2. utime == microsecond time? (u as micro prefix)
The same would occur if we used 'stime' for scalar time, does it mean signed, or seconds? Another bad prefix.
Yes, rbb is right here, apr_time_t is the only type name that makes a ton of
sense. Perhaps [since this isn't a structure, and it isn't opaque] we revisit
Roy's suggestion of apr_time (with no suffix) so it no longer looks like posix,
and it breaks the name as Aaron's veto demands. apr_timediff or apr_timespan
are probably the best companions to the 1.1.70 epoch apr_time type.
Drop _t since this is a scalar type and not a structure/opaque?
With apr_time... our functions can stay as is.
So, simple question: What is a busec? I obviously know the answer, it is a binary usec. How many of APR users do you honestly expect to look at busec and think that?
They won't. They will ask WTF is a busec? They will look, and discover that
it's a binary usec. In the doc sections for both apr_time and apr_timediff/span
we point them @see {group} apr_time_macros. There they find all the macros.
We tell them what it is, and suggest they use macros in case of future changes (and for legibility in code.)
Now, we are also talking about having macros to convert to and from decimal time values. So, that would essentially be:
Apr_busec_sec Apr_busec_usec Apr_busec_msec
No, simpler... apr_time_from_[x]sec/apr_time_to_[x]sec. where x is m, u, n or simply sec. Those convert between apr_time quantums and decimal scales.
apr_time_[x]sec_get / apr_time_[x]sec_put deals ONLY with the specific units, the integral seconds, and the fractional m/u/n seconds. So _gets of the apr_time t for 33.25 seconds would return;
apr_time_sec_get(t) == 33 apr_time_msec_get(t) == 250 apr_time_usec_get(t) == 250000 apr_time_nsec_get(t) == 250000000
The _[x]sec_put macros do the converse, with no range checking of the input. They are *considerably* faster, because we won't worry about overflow. We expect a number less than 1 second for the m/u/nsec flavors. You simply should not use _usec_put when what you really want is apr_time_from_usec, or you quite probably will be truncated.
Even simpler is apr_time_[x]make, so you can provide sec, usec or whatever other pair you want, and have your time of it.
A way to compare and operate on time:
Apr_busec_add Apr_busec_sub
Those are BS. This is a SCALAR. It will always remain a scalar, lest our performance takes a flying leap from the window.
Now, we still need a way to get to the current time:
Apr_busec_now
apr_time_now ... the fn name WON'T CHANGE.
This is actually why I'm really appreciating Roy's suggestion of apr_time as the type name. It's why I suggested apr_time_busec so we could spare the rename. But 'busec' as part of the type name is out of consideration.
Convert to a human-readable form:
Apr_explode_time Apr_explode_localtime
Please reassure me that we've fixed all those old names long ago, and you were just recalling the old forms.
22 functions/macros to deal with time. 8 of those are because we are storing time in a format that nobody else expects.
We have those today. We have them because we deal in uniform apr_time_t RIGHT NOW TODAY. This whole proposal changes nothing in that department.
How does apr_poll deal with time? Does it use apr_busec_interval_t or "number of seconds to wait"? If it uses apr_busec_interval_t, then every single call to poll (and every other apr function that accepts a timeout arg) becomes:
Apr_poll(pollset, 1, &nsds, apr_sec_busec(5));
Yup. (well, pass apr_time_from_sec(5) instead). This is what we expect from apr_sockopt and all other timeouts. They take apr_time_t today (or rather, apr_time_short_interval_t... which Roy observed and I agree is bogus.)
If it accepts "number of seconds to wait", then EVER apr function that accepts a timeout arg needs to do its own conversion. Which, BTW is a bad idea, because keeping it straight when you are using apr_busec_t and when you are using "number of seconds" inside the library will be very difficult to keep track of, and it is almost guaranteed to cause bugs.
That's unacceptable, I agree. I'm working on solving this in two ways:
1. as Roy pointed out, our current 32bit intervals are bogus. I'm changing
apr_getsockopt/setsockopt(... APR_SO_TIMEOUT...) into the typesafe
and saner apr_socket_timeout_get/set() (passing and returning through
an apr_interval_time_t, using today's name). That patch is forthcoming.2. we already have this issue on win32, and I don't like where we are right now.
Win32 is using msec, but we pass and return usec values. That's just sure
to introduce bugs. I'm going to cache *two* values in the socket_t structure,
s->timeout and s->timeout_ms. This makes state changes quick, but keeps
the data readily available for recall with getsockopt().
So unix -could- keep a tm handy if you need sec/usec as an argument, and only set that value up once, each time we call timeout_set. That's a performance call I'm certain BPane will weight in on later. But it's totally internal and transparent to our library user.
Either one of these solutions is most likely going to cause enough pain to the developer that APR's time code will be used rarely, IMHO.
That's Roy's complaint already that we aren't using seconds. And I think (so far) we've proven that point incorrect.
You are arguing that our usec times made sense, others argue that they really didn't. We are now suggesting 'Trust Us - Use Macros - Kill Bugs'. Since the macros are completely processed at compile time for const values, they are the best solution.
Maybe would could have had:
#ifndef NEW_TIME_FMT #error "Please convert you code to use busec's #endif
Interesting option :-) But not entirely practical, I think. It doesn't take into
account the developer's own header files that might contain time constants.
