[Developers] Proposed Cactus Timer API Completion

Jonathan Thornburg jthorn at aei.mpg.de
Tue Aug 3 08:39:26 CDT 2004


Hi, Steve,

I agree with you that the current timer API is clumsy, and I would
love to see a cleanup like you propose!  A few other comments on the
details of your new API:

> 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.

Do these functions return pointers to data which is already stored
somewhere inside the timer system?
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).

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)

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.


> 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?

Maybe this would be clearer to me if I reread the Cactus Users' Guide
section on timers...

ciao,

-- 
-- Jonathan Thornburg <jthorn at aei.mpg.de>      
   Max-Planck-Institut fuer Gravitationsphysik (Albert-Einstein-Institut),
   Golm, Germany, "Old Europe"     http://www.aei.mpg.de/~jthorn/home.html      
   "Washing one's hands of the conflict between the powerful and the
    powerless means to side with the powerful, not to be neutral."
                                      -- quote by Freire / poster by Oxfam




More information about the Developers mailing list