[Developers] Proposed Cactus Timer API Completion

Steve White swhite at aei.mpg.de
Mon Aug 9 04:12:27 CDT 2004

Detailed enough for what?  Please provide more information.

I wrote it in the style of the existing docs in the Users Guide.

I am not re-writing the existing timer API, I'm completing the existing
one to make it usable. This completion is not really comprehensible
outside the existing Cactus timer context.

As it now stands, the additional functions in cctk_Timers.h are

unsigned int
CCTK_NumTimerClocks( const cTimerData *info );

const cTimerVal *
CCTK_GetClockValueI( int valno, const cTimerData *info );

const cTimerVal *
CCTK_GetClockValue( const char * name, const cTimerData *info );

CCTK_TimerClockSeconds( const cTimerVal *clockVal );

const char *
CCTK_TimerClockName( const cTimerVal *clockVal );

Given one understands that each Cactus timer starts multiple clocks, the
only thing that isn't bloody is use of the 'GetClockValue' functions.  But
they follow the pattern of the existing functions.  The 'I' indicates to
get the clock value by index; otherwise you get it by clock name.

Since they aren't named 'Create' or 'Make' or 'Allocate', and since there
is no 'Free' function, you can surmise that there's no need to free

But this is all explained in the documentation.

On Sat, 7 Aug 2004, Jonathan Thornburg wrote:
> Quoting from your E-mail of Thu, 5 Aug 2004 18:49:22 +0200 (CEST):
> > Here is the latest version of the proposed completion of the Timer API.
> I'm sorry, this is just not detailed enough.  After rereading it
> many times I am still guessing at some details of what the functions do.
> Could you perhaps post your draft of an actual API, i.e. with
> actual C and/or Fortran function prototypes?  Some sample client
> code showing typical usage would also be VERY useful in understanding
> how the various pieces fit totether.

> Are these proposed functions in *addition* to the existing ones in
> section B10.1.2 "Timing Calls" of the Cactus Users' Guide, or are
> they intended to *replace* the existing calls?
Complete, not replace.

> > CCTK_NumTimerClocks
> > 
> > Take a pointer to cTimerData and return the number of clocks recorded in a
> > timer measurement
> I presume you mean "the number of different clocks recorded"
> -- it took me considerable puzzling to determime that you meant that,
> and not "the number of clock ticks (eg CPU cycles) recorded".
The notion of clocks is something special to the Cactus timer API.
Not my idea, but there it is, and it does have some nice properties.

> Looking at the Cactus Users' Guide, section B10.1 "Using Cactus Timers",
>  struct cTimerData  includes an  n_vals  field.  (In what way) does
> CCTK_NumTimerClocks() differ from just looking at the value of that field?
In the same way that calling an API function usually removes the user
from the underlying implementation details.

> Are you proposing to keep the format of  struct cTimerData  public
> (as in section B10.1.3), or make it opaque?  Ditto on  struct cTimerVal ?
Opaque as a black cat when you're trying to read a newspaper.

> > CCTK_GetClockValue, CCTK_GetClockValueI
> > 
> > Given a clock referred to by name or index, respectively, and a cTimerData
> > pointer, return a cTimerVal pointer representing the value of the clock
> > when the timer was stopped
> Who owns the cTimerVal structure which the returned pointer points to?
> That is, if I call one of these functions N times in a row, does someone
> malloc N cTimerVal structures, so that I get N distinct pointers?  Or
> is there only a single static structure, which gets overwritten with
> each call?
The timer owns it.  The user doesn't have to think about this.

> I think it would be MUCH cleaner for the caller to pass in a pointer
> to a cTimerVal struct, and the function to fill in that struct.
> That way the ownership/lifetime issues are clear, and multiple clients
> can use these calls concurrently without interference.
Unnecessary, given there is no ownership issue.  

Not cleaner.  The user would then have to dispose of their copy.

> > CCTK_TimerClockName
> > 
> > Return the name of the clock given by the cTimerVal pointer argument.
> (In what way) does this differ from the  heading  member of  struct cTimerVal ?
See above about the general purpose of an API.
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