[Developers] Proposed Cactus Timer API Completion

Steve White swhite at aei.mpg.de
Tue Aug 3 12:38:20 CDT 2004

On Tue, 3 Aug 2004, Jonathan Thornburg wrote:

> > const cTimerVal *
> > CCTK_GetClockValNumber( int clockno, const cTimerData *info );
> > 	// Gets the clock value with the given number from the 
> > 	// timer measurement
> > 
> > const cTimerVal *
> > CCTK_GetClockValNamed( const char * name, const cTimerData *info );
> > 	// Gets the clock value for the clock with the given name
> > 	// from the timer measurement
> > 
> > const char *
> > CCTK_TimerClockName( const cTimerVal *clockVal );
> >         // Gets the name of the clock corresponding to the clock value
> I'm not really clear on what the verb "Gets" means here.
I'm not in love with these function names.

> Do these functions return pointers to data which is already stored
> somewhere inside the timer system?
They do.  I have in fact already written and tested the calls.
They just refer to things, they don't alter any information.

> If so,
> * do these pointers point into static buffers, potentially overwritten
>   with each call?  (this is bad for multithreading)
> * otherwise, for how long is the data they point to, valid?
> In any case, maybe "Returns a pointer to" would be an clearer
> phrase to describe what these functions do?
> I think a cleaner (and multithread-safe) solution might be for the
> caller to pass in a pointer to a buffer where the result is to be
> stored -- that's the general style with other Cactus APIs (and with
> modern Unix APIs in general).
The information is already stored.  It is allocated within the current
process by the other Timer calls.  I don't think there are any "static
buffers" involved.

First, I'm not doing anything the existing timer system doesn't do.
So if this API is unsafe, so was the existing one.

I'm trying to make a minimal set of changes to the existing API to make
it usable.  

> It would also be good to return a status code, so we can signal errors
> (eg 'clockno' is invalid).  For example,
>   int status =
>      CCTK_GetClockValNumber( int clockno, const cTimerData *info,
> 			     cTimerVal* clock_value)
>   int status =
>      CCTK_GetClockValNamed( const char * name, const cTimerData *info,
> 			    cTimerVal* clock_value)
The ones I wrote return NULL if they fail.

> For CCTK_TimerClockName() I would say the caller should pass in a
> pointer to a buffer and also a buffer size, and we should return some
> information which allows the caller to determine if the result was
> truncated.  See  Util_TableGetString()  for what I think is a clean
> design here.
I dunno.  Much messier interface for not a big improvement.  The right
solution is a String module. 

As it is, the documentation should mention that the user should copy the
string if they mean to keep it.  The string exists in the Timer structure
which goes away when deleted by the user.

Once again, this is no different from the way the existing Timer works.

> > double
> > CCTK_TimerClockSeconds( const cTimerVal *clockVal );
> > 	// Gets the value of the measurement in seconds from the clock
> > 	// value
> I'm not clear on the semantics of this.  If the timer is counting
> wall-clock time or per-process CPU time, everything is ok, but what
> should this function return if the timer is counting (say) L2 cache misses?
As I explained in my note to Gab, a Timer should be measuring time, not
counting L2 cache misses.

The only thing I would add to this is that it's sometimes also useful
to know the granularity of the clock.  But given that you have a way
to determine that, it would be easy to write another accessor.

Steve White : Programmer
Max-Planck-Institut für Gravitationsphysik      Albert-Einstein-Institut
Am Mühlenberg 1, D-14476 Golm, Germany                  +49-331-567-7329

More information about the Developers mailing list