[Developers] Proposed Cactus Timer API Completion
jshalf at lbl.gov
Tue Aug 10 18:14:56 CDT 2004
do you want any non-get-time-of-day counter/timer examples?
For instance, I've got timers that use PAPI, HPMCOUNT, and
Linux RTC counters to extract timing info at sub-microsecond
I've been having significant problems with the gettimeofday()
based counter-timers giving incorrect results on the Cray and
NEC systems due to timer granularity issues. I can provide
you with some specific examples where the Cactus timers
diverged from the hardware performance counters by 200%
or more in the final timer dump. So hiding more accurate
counter/timers beneath your API will be very useful
from my standpoint.
In order to support these "hidden timers", the timer API
would benefit from simple opaque addition/subtraction
operators. Internally, you can use a timer-dependent
accurate mechanism for performing the addition/subtraction
I think someone requested a subroutine call to request the
timer granularity. I think collecting that data will be useful
to keep for the innards of your timing API for sanity checks.
For instance, if the elapsed time for any timer start/stop
event is < 8x the timer granularity, this should set some kind
of "flag" associated with that timer to indicate that its results
are not to be trusted. So I'd advocate incorporating the
timer granularity into your API design even if that information
is only used internal to the timing API.
On Aug 9, 2004, at 2:12 AM, Steve White wrote:
> 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,
> only thing that isn't bloody is use of the 'GetClockValue' functions.
> they follow the pattern of the existing functions. The 'I' indicates
> 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
> 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
>> 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
>> 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.
>>> 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
>> struct cTimerData includes an n_vals field. (In what way) does
>> CCTK_NumTimerClocks() differ from just looking at the value of that
> 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
>>> pointer, return a cTimerVal pointer representing the value of the
>>> 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
>> 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.
>>> 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
> Am Mühlenberg 1, D-14476 Golm, Germany
> Developers mailing list
> Developers at cactuscode.org
More information about the Developers