Added Cactus Timer functions documentation

git-svn-id: http://svn.cactuscode.org/flesh/trunk@3847 17b73243-c579-4c4c-a9d2-2d5706c11dac

1 files changed, 557 insertions, 0 deletions

diff --git a/doc/ReferenceManual/CCTKReference.tex b/doc/ReferenceManual/CCTKReference.tex
index 07ad6e6f..84a04a8f 100644
--- a/doc/ReferenceManual/CCTKReference.tex
+++ b/doc/ReferenceManual/CCTKReference.tex
@@ -68,6 +68,9 @@ from Fortran.
 \item[\code{CCTK\_Barrier}] [\pageref{CCTK-Barrier}]
   Synchronizes all processors
 
+\item[\code{CCTK\_ClockRegister}] [\pageref{CCTK-ClockRegister}]
+  Registers a new named clock with the Flesh.
+
 \item[\code{CCTK\_Cmplx}] [\pageref{CCTK-Cmplx}]
   Turns two real numbers into a complex number (only C)
 
@@ -197,6 +200,25 @@ from Fortran.
 \item[\code{CCTK\_FullName}] [\pageref{CCTK-FullName}]
   Given a variable index, returns the full name of the variable
 
+\item[\code{CCTK\_GetClockName}] [\pageref{CCTK-GetClockName}]
+  Given a pointer to a clock {\t cTimerVal} structure, returns the name
+  of the clock.
+
+\item[\code{CCTK\_GetClockResolution}] [\pageref{CCTK-GetClockResolution}]
+  Given a pointer to a clock {\t cTimerVal} structure, returns the resolution
+  of the clock.
+
+\item[\code{CCTK\_GetClockSeconds}] [\pageref{CCTK-GetClockSeconds}]
+  Given a pointer to a clock {\t cTimerVal} structure, returns the elapsed time.
+
+\item[\code{CCTK\_GetClockValue}] [\pageref{CCTK-GetClockValue}]
+  Given the name of a clock, returns a pointer to the corresponding
+  {\t cTimerVal} structure within the {\t cTimerData} structure.
+
+\item[\code{CCTK\_GetClockValueI}] [\pageref{CCTK-GetClockValueI}]
+  Given the index of a clock, returns a pointer to the corresponding
+  {\t cTimerVal} structure within the {\t cTimerData} structure.
+
 \item[\code{CCTK\_GHExtension}] [\pageref{CCTK-GHExtension}]
   Get the pointer to a registered extension to the Cactus GH structure
 
@@ -452,6 +474,9 @@ from Fortran.
 \item[\code{CCTK\_NumTimeLevelsVN}] [\pageref{CCTK-NumTimeLevels}]
   Returns the number of active timelevels from a variable name (deprecated)
 
+\item[\code{CCTK\_NumTimerClocks}] [\pageref{CCTK-NumTimerClocks}]
+  Returns the number of clocks in a {\t cTimerData} structure.
+
 \item[\code{CCTK\_NumVars}] [\pageref{CCTK-NumVars}]
   Get the number of grid variables compiled in the code
 
@@ -594,6 +619,50 @@ from Fortran.
   [\pageref{CCTK-ThornImplementation}]
   Returns the implementation provided by the thorn
 
+\item[\code{CCTK\_Timer}] [\pageref{CCTK-Timer}]
+  Fills a timer {\t cTimerData} structure with current values of all clocks
+  of a timer with a given name.
+
+\item[\code{CCTK\_TimerCreate}] [\pageref{CCTK-TimerCreate}]
+  Create a timer with a given name, returns a timer index.
+
+\item[\code{CCTK\_TimerCreateData}] [\pageref{CCTK-TimerCreateData}]
+  Allocates a timer {\t cTimerData} structure.
+
+\item[\code{CCTK\_TimerCreateI}] [\pageref{CCTK-TimerCreateI}]
+  Create an unnamed timer, returns a timer index.
+
+\item[\code{CCTK\_TimerDestroy}] [\pageref{CCTK-TimerDestroy}]
+  Reclaims resources for a timer with a given name.
+
+\item[\code{CCTK\_TimerDestroyData}] [\pageref{CCTK-TimerDestroyData}]
+  Reclaims resources of a timer {\t cTimerData} structure.
+
+\item[\code{CCTK\_TimerDestroyI}] [\pageref{CCTK-TimerDestroyI}]
+  Reclaims resources for a timer with a given index.
+
+\item[\code{CCTK\_TimerI}] [\pageref{CCTK-TimerI}]
+  Fills a timer {\t cTimerData} structure with current values of all clocks
+  of a timer with a given index.
+
+\item[\code{CCTK\_TimerReset}] [\pageref{CCTK-TimerReset}]
+  Initialises the timer with a given name.
+
+\item[\code{CCTK\_TimerResetI}] [\pageref{CCTK-TimerResetI}]
+  Initialises the timer with a given index.
+
+\item[\code{CCTK\_TimerStart}] [\pageref{CCTK-TimerStart}]
+  Initialises the timer with a given name.
+
+\item[\code{CCTK\_TimerStartI}] [\pageref{CCTK-TimerStartI}]
+  Initialises the timer with a given index.
+
+\item[\code{CCTK\_TimerStop}] [\pageref{CCTK-TimerStop}]
+  Gets current values for all clocks of the timer with a given name.
+
+\item[\code{CCTK\_TimerStopI}] [\pageref{CCTK-TimerStopI}]
+  Gets current values for all clocks of the timer with a given index.
+
 \item[\code{CCTK\_VarDataPtr}] [\pageref{CCTK-VarDataPtr}]
   Returns the data pointer for a grid variable
 
@@ -1069,6 +1138,33 @@ it must be called by all processors otherwise the code will hang.
 % CCC
 %%%%%
 
+\begin{CCTKFunc}{CCTK\_ClockRegister}{Registers a named timer clock
+with the Flesh.}
+\label{CCTK-ClockRegister}
+\subroutine{int}{}{}
+\showcargs
+\begin{params}
+\parameter{const char *}{name}
+\parameter{const cClockFuncs *}{functions}
+\end{params}
+\begin{discussion}
+The {\t cClockFuncs} structure contains function pointers defined by
+the clock module to be registered.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t err = CCTK\_ClockRegister("myNewClock", functions)}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+A negative return value indicates an error.
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+\begin{CCTKFunc}{CCTK\_TimerDestroy}{Reclaims resources used by the
+
 \begin{CCTKFunc}{CCTK\_Cmplx}{Turns two real numbers into a complex number}
 \label{CCTK-Cmplx}
 \subroutine{CCTK\_COMPLEX}{}{cmpno}
@@ -7314,6 +7410,467 @@ Error.
 
 
 
+\begin{CCTKFunc}{CCTK\_TimerCreate}{Creates a timer with a given name,
+returns an index to the timer.}
+\label{CCTK-TimerCreate}
+\subroutine{int}{}{}
+\argument{const char *}{}{name}
+\showcargs
+\begin{params}
+\parameter{name}{C string }
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t myTimer = CCTK\_TimerCreate("myTimer")}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+A negative return value indicates an error.
+\end{errorcodes}
+\end{CCTKFunc}
+
+\begin{CCTKFunc}{CCTK\_TimerCreateI}{Creates an unnamed timer,
+returns an index to the timer.}
+\label{CCTK-TimerCreateI}
+\subroutine{int}{}{}
+\showcargs
+\begin{params}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t myTimer = CCTK\_TimerCreateI()}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+A negative return value indicates an error.
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+\begin{CCTKFunc}{CCTK\_TimerDestroy}{Reclaims resources used by the
+given timer, specified by name.}
+\label{CCTK-TimerDestroy}
+\subroutine{int}{}{}
+\argument{const char *}{}{name}
+\showcargs
+\begin{params}
+\parameter{name}{C string}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t err = CCTK\_TimerDestroy("myTimer")}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+A negative return value indicates an error.
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+\begin{CCTKFunc}{CCTK\_TimerDestroyI}{Reclaims resources used by the
+given timer, specified by index.}
+\label{CCTK-TimerDestroyI}
+\subroutine{int}{}{}
+\argument{int}{}{index}
+\showcargs
+\begin{params}
+\parameter{index}{timer index}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t err = CCTK\_TimerDestroy(2)}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+A negative return value indicates an error.
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+\begin{CCTKFunc}{CCTK\_TimerStart}{Initialises all the clocks in the
+given timer, specified by name.}
+\label{CCTK-TimerStart}
+\subroutine{int}{}{}
+\argument{const char *}{}{name}
+\showcargs
+\begin{params}
+\parameter{name}{C string}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t err = CCTK\_TimerStart("myTimer")}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+A negative return value indicates an error.
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+\begin{CCTKFunc}{CCTK\_TimerStartI}{Initialises all the clocks in the
+given timer, specified by index.}
+\label{CCTK-TimerStartI}
+\subroutine{int}{}{}
+\argument{int}{}{index}
+\showcargs
+\begin{params}
+\parameter{index}{timer index}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t err = CCTK\_TimerStart(2)}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+A negative return value indicates an error.
+\end{errorcodes}
+\end{CCTKFunc}
+
+\begin{CCTKFunc}{CCTK\_TimerStop}{Gets values from all the clocks in the
+given timer, specified by name.}
+\label{CCTK-TimerStop}
+\subroutine{int}{}{}
+\argument{const char *}{}{name}
+\showcargs
+\begin{params}
+\parameter{name}{C string}
+\end{params}
+\begin{discussion}
+Call this before getting the values from any of the timer's clocks.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t err = CCTK\_TimerStop("myTimer")}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+A negative return value indicates an error.
+\end{errorcodes}
+\end{CCTKFunc}
+
+\begin{CCTKFunc}{CCTK\_TimerStopI}{Gets values from all the clocks in the
+given timer, specified by index.}
+\label{CCTK-TimerStopI}
+\subroutine{int}{}{}
+\argument{int}{}{index}
+\showcargs
+\begin{params}
+\parameter{index}{timer index}
+\end{params}
+\begin{discussion}
+Call this before getting the values from any of the timer's clocks.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t err = CCTK\_TimerStopI(2)}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+A negative return value indicates an error.
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+\begin{CCTKFunc}{CCTK\_TimerReset}{Resets all the clocks in the
+given timer, specified by name.}
+\label{CCTK-TimerReset}
+\subroutine{int}{}{}
+\argument{const char *}{}{name}
+\showcargs
+\begin{params}
+\parameter{name}{C string}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t err = CCTK\_TimerReset("myTimer")}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+A negative return value indicates an error.
+\end{errorcodes}
+\end{CCTKFunc}
+
+\begin{CCTKFunc}{CCTK\_TimerResetI}{Gets values from all the clocks in the
+given timer, specified by index.}
+\label{CCTK-TimerResetI}
+\subroutine{int}{}{}
+\argument{int}{}{index}
+\showcargs
+\begin{params}
+\parameter{index}{timer index}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t err = CCTK\_TimerResetI(2)}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+A negative return value indicates an error.
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+\begin{CCTKFunc}{CCTK\_TimerCreateData}{Allocates the {\tt cTimerData} 
+structure, which is used to store timer clock info.}
+\label{CCTK-TimerCreateData}
+\subroutine{cTimerData *}{}{ptr}
+\showcargs
+\begin{params}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t cTimerData *data = CCTK\_TimerCreateData()}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+A null return value indicates an error.
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+\begin{CCTKFunc}{CCTK\_TimerDestroyData}{Releases resources from the 
+{\tt cTimerData} 
+structure, created by {\tt CCTK\_TimerCreateData}.}
+\label{CCTK-TimerDestroyData}
+\subroutine{int}{}{}
+\showcargs
+\begin{params}
+\parameter{cTimerData *}{timer clock info pointer}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t err = CCTK\_TimerDestroyData( data )}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+A negative return value indicates an error.
+\end{errorcodes}
+\end{CCTKFunc}
+
+\begin{CCTKFunc}{CCTK\_Timer}{Fills a {\tt cTimerData} 
+structure with timer clock info, for the timer specified by name.}
+\label{CCTK-Timer}
+\subroutine{int}{}{}
+\showcargs
+\begin{params}
+\parameter{const char *}{timer name}
+\parameter{cTimerData *}{timer clock info pointer}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t err = CCTK\_Timer("myTimer", info)}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+A negative return value indicates an error.
+\end{errorcodes}
+\end{CCTKFunc}
+
+\begin{CCTKFunc}{CCTK\_TimerI}{Fills a {\tt cTimerData} 
+structure with timer clock info, for the timer specified by index.}
+\label{CCTK-TimerI}
+\subroutine{int}{}{}
+\showcargs
+\begin{params}
+\parameter{int}{timer index}
+\parameter{cTimerData *}{timer clock info pointer}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t err = CCTK\_Timer(2, info)}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+A negative return value indicates an error.
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+\begin{CCTKFunc}{CCTK\_NumTimerClocks}{Given a {\tt cTimerData} 
+structure, returns its number of clocks.}
+\label{CCTK-NumTimerClocks}
+\subroutine{int}{}{}
+\showcargs
+\begin{params}
+\parameter{const cTimerData *}{timer info pointer}
+\end{params}
+\begin{discussion}
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t nClocks = CCTK\_NumTimerClocks(info)}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+\begin{CCTKFunc}{CCTK\_GetClockValue}{Given a name of a clock that is
+in the given {\tt cTimerData} structure,
+returns a pointer to the {\tt cTimerVal} structure holding the clock's value.}
+\label{CCTK-GetClockValue}
+\subroutine{const cTimerVal *}{}{ptr}
+\showcargs
+\begin{params}
+\parameter{const char *}{timer clock name}
+\parameter{const cTimerData *}{timer info pointer}
+\end{params}
+\begin{discussion}
+Do not attempt to free the returned pointer directly.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t const cTimerVal *myVal = CCTK\_GetClockValue("getrusage", info )}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+\begin{CCTKFunc}{CCTK\_GetClockValueI}{Given the index of a clock 
+in the given {\tt cTimerData} structure,
+returns a pointer to the {\tt cTimerVal} structure holding the clock's value.}
+\label{CCTK-GetClockValueI}
+\subroutine{const cTimerVal *}{}{ptr}
+\showcargs
+\begin{params}
+\parameter{int}{timer clock index}
+\parameter{const cTimerData *}{timer info pointer}
+\end{params}
+\begin{discussion}
+Do not attempt to free the returned pointer directly.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t const cTimerVal *myVal = CCTK\_GetClockValueI(0, info )}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+\begin{CCTKFunc}{CCTK\_GetClockName}{Given a pointer to the {\tt cTimerVal}
+corresponding to a timer clock returns a pointer to a string that is
+the name of the clock}
+\label{CCTK-GetClockName}
+\subroutine{const char *}{}{ptr}
+\showcargs
+\begin{params}
+\parameter{const cTimerVal *}{timer clock value pointer}
+\end{params}
+\begin{discussion}
+Do not attempt to free the returned pointer directly.  You must use the
+string before calling {\tt CCTK\_TimerDestroyData} on the containing
+timer info.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t const char *name = CCTK\_GetClockName(val)}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+\begin{CCTKFunc}{CCTK\_GetClockSeconds}{Given a pointer to the {\tt cTimerVal}
+corresponding to a timer clock returns a the elapsed time in seconds between
+the preceding {\tt CCTK\_TimerStart} and {\tt CCTK\_TimerStop} as recorded
+by the requested clock. }
+\label{CCTK-GetClockSeconds}
+\subroutine{double}{}{}
+\showcargs
+\begin{params}
+\parameter{const cTimerVal *}{timer clock value pointer}
+\end{params}
+\begin{discussion}
+Be aware, different clocks measure different things (proper time,
+CPU time spent on this process, etc.), and have varying resolution
+and accuracy.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t double secs = CCTK\_GetClockSeconds(val)}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+
+\begin{CCTKFunc}{CCTK\_GetClockResolution}{Given a pointer to the
+{\tt cTimerVal} corresponding to a timer clock returns the resolution of
+the clock in seconds. }
+\label{CCTK-GetClockResolution}
+\subroutine{double}{}{}
+\showcargs
+\begin{params}
+\parameter{const cTimerVal *}{timer clock value pointer}
+\end{params}
+\begin{discussion}
+Ideally, the resolution should represent a good lower bound on the smallest
+non-zero difference between two consecutive calls of {\t CCTK\_GetClockSeconds}.
+In practice, it is sometimes far smaller than it should be.  Often it just
+represents the smallest value representable due to how the information is
+stored internally.
+\end{discussion}
+\begin{examples}
+\begin{tabular}{@{}p{3cm}cp{11cm}}
+\hfill {\bf C} && {\t double resolution = CCTK\_GetClockResolution(val)}\\
+\\
+\end{tabular}
+\end{examples}
+\begin{errorcodes}
+\end{errorcodes}
+\end{CCTKFunc}
+
+%%%%%
+
 %%%%%
 % UUU
 %%%%%