Expanded on chapter Infrastructure:Adding a timer

Renamed it to "Adding a timer clock"
Corrected references to "Timer" in this section to "Clock"

Made links from this chapter to the section "Using Cactus Timers"
and vice-versa.


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

2 files changed, 36 insertions, 11 deletions

diff --git a/doc/UsersGuide/Infrastructure.tex b/doc/UsersGuide/Infrastructure.tex
index f628e20d..2dd4119e 100644
--- a/doc/UsersGuide/Infrastructure.tex
+++ b/doc/UsersGuide/Infrastructure.tex
@@ -576,27 +576,52 @@ provides distinct timebins for recovery routines to be scheduled at:
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-\chapter{Adding a timer}
+\chapter{Adding a timer clock}
+\label{chap:clocks}
 
-To add a Cactus timer you need to write several functions to provide the
-timer functionality, and then register these functions with the Flesh, with a name for the timer using {\t CCTK\_TimerRegister}.
+To add a Cactus timer clock you need to write several functions to provide the
+clock functionality (see Section \ref{sec:timers}), and then register these
+functions with the Flesh as a named clock.
 
-The functions are registered using a structure {\t cTimerFuncs} which
-contains the function pointers. The required functions are:
+The function pointers are placed in function pointer fields of a 
+\texttt{cClockFuncs} sturcture.  The fields of this structure are are:
 
 \begin{Lentry}
 
-\item[{\t info.n\_vals}]
-\item[{\t create}] {\t void *(*create)(int);}
+\item[{\t create}] {\t void *(*create)(int)}
 \item[{\t destroy}] {\t void (*destroy)(int, void *)}
 \item[{\t start}] {\t void (*start)(int, void *)}
 \item[{\t stop}] {\t void (*stop)(int, void *)}
 \item[{\t reset}] {\t void (*reset)(int, void *)}
 \item[{\t get}] {\t void (*get)(int, void *, cTimerVal *)}
 \item[{\t set}] {\t void (*set)(int, void *, cTimerVal *)}
+\item[{\t n\_vals}] {\t int}
 
 \end{Lentry}
 
+The first \texttt{int} argument of the functions may be used in any way
+you see fit.
+
+The return value of the \texttt{create} function will be a pointer to
+a new structure representing your clock.
+
+The second \texttt{void*} argument of all the other functions will be the
+pointer returned from the \texttt{create} function.
+
+The \texttt{cTimerVal*} argument of the \texttt{get} and \texttt{set}
+functions is as described in Section \ref{subsec:cTimerData}.
+
+The \texttt{n\_vals} field holds the number of elements in the 
+\texttt{vals} array field of the \texttt{cTimerVal} structure 
+used by your timer.
+
+To name and register the clock with the Flesh, call the function
+\begin{verbatim}
+	CCTK_ClockRegister( "my_clock_name", &clock_func ).
+\end{verbatim}
+
+
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
diff --git a/doc/UsersGuide/ThornWriters.tex b/doc/UsersGuide/ThornWriters.tex
index 62a75a0c..a98b80f1 100644
--- a/doc/UsersGuide/ThornWriters.tex
+++ b/doc/UsersGuide/ThornWriters.tex
@@ -3411,6 +3411,7 @@ For details on running the test suites, see Section~\ref{sec:testing}.
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{Using Cactus Timers}
+\label{sec:timers}
 
 \subsection{What are timers?}
 
@@ -3422,10 +3423,8 @@ timing different sections of your thorns using various clocks which
 have been registered with the Flesh.  By default, the Flesh provides a
 set of clocks (if they are available), measuring for
 example wall clock time and CPU time. Additional clocks can be
-implemented by thorns and registered with the Flesh
-%(see
-%Section~\ref{????} [FIXME: clock registration to be added]
-%on how to write and register your own clock).
+implemented by thorns and registered with the Flesh (see Chapter
+\ref{chap:clocks}).
 
 You can add any number of timers to your thorn source code, providing
 each with a chosen name, for example {\tt TimeMyRoutine}, {\tt TimeNextCalculation}, and then use Cactus functions to switch on the
@@ -3483,6 +3482,7 @@ Provide the name of the timer for a given timer index
 \end{Lentry}
 
 \subsection{The {\tt cTimerData} Structure}
+\label{subsec:cTimerData}
 
 The structure holding the timing data, {\tt cTimerData}, contains
 the number of collected times (one measurement for each registered clock),