[Developers] Proposed Cactus Timer API Completion

Jonathan Thornburg jthorn at aei.mpg.de
Sat Aug 7 09:11:38 CDT 2004

Hi, Steve,

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?

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

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?

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 ?

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

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.

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

> CCTK_TimerClockSeconds
> Return the floating-point value of the measurement in seconds from the
> cTimerVal pointer argument.


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