> From: William A. Rowe, Jr. [mailto:[EMAIL PROTECTED]
>
> 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.
Yep, we have to choose a name that doesn't require the user to sit and
do research for hours to figure out what we are saying. Sorry, but
anything else is completely unacceptable.
> 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?
I can accept apr_time.
> >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.
That is unacceptable. The types have to make sense, or they just aren't
useful. If everytime somebody new wants to use APR, they have to look
up what apr_utime or apr_busec or apr_foo is, they will drop APR very
quickly.
> >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.
So my names are wrong, but the concept is the same. More macros than
you can keep straight to fill in the time structure. The advantage to
the current model, is that there is one macro: APR_SEC_FROM_USEC.
>
> 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
In fact, you added one more macro, the nsec variant, so now you have
_10_ macros to get information out of a simple time type. That doesn't
seem incredibly extreme to you?
> >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.
I may be wrong, but I explicitly remember seeing those macros being
discussed.
>
> >Now, we still need a way to get to the current time:
> >
> >Apr_busec_now
>
> apr_time_now ... the fn name WON'T CHANGE.
So what, the function exists. Yes, it exists today, but I was merely
pointing out that you are going from 14 time functions and 1 macro to 14
functions and 10 macros (was 8 in my last e-mail, but the [n] variant
wasn't in my count).
> >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.
Nope, those came straight out of the headers.
> >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.
Sure it does. We have 1 macro today, now we need 10!
> >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.)
great, that means that EVERY single call that deals with time in EVERY
single APR app needs to change. And, it means that calling those
functions will just become a painful exercise for new programmers.
"Let's see, I need to pass an apr_time value, which is a binary usec
implementation, now, how do I get binary usec's again? I guess I'll go
read the docs to find out." Programming used to make sense, because the
types made sense and for simple things, like timeouts, programmers could
use simple values. Now, our timeouts are incredibly complex, which
makes using them painful. :-(
> 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().
And guarantees bugs. :-( Caching speeds things up, but it is almost
guaranteed to cause somebody to update 1 of them without updating the
other at some point in the future. Data duplication is almost never a
good idea.
> 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.
And has the same problem, that in the name of performance, you are going
to introduce bugs.
> >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.
I am simply suggesting nobody has weighed in from the user's point of
view, other than to say "We must have usec resolution". The API that is
currently being discussed is big and complex. I would personally never
write a program using APR if a concept as simple as time required this
much work to get into my program. This API would literally stop me from
using APR at all, because of how often I would need to read the docs on
how to use the API.
How often do the programmers on this list look at the docs for simple
functions, like poll or read/write. I'm willing to bet almost never,
because the APIs were designed so that they made sense once you learned
them. The time API that is being designed doesn't make sense to me as a
programmer, which means that I will spend most of my time reading the
docs on how to use it, which means I am unlikely to use it or any of
APR, because time goes throughout APR.
No disrespect intended at all here, but the API being designed reminds
me very much of the native functions on Windows. Ten ways to do
everything, and all of them require far too much work to understand.
> >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.
Sure it does. It is just saying that if you include the apr_time.h
header, you will have to define an APR specific macro to prove that you
are using the new definition of apr_time_t.
Ryan
