\chapter{Timers, Periodic Checks, and Conditions}

This module provides functions that allow users to insert hooks,
i.e. user-supplied functions, that are called by the system at
as specific conditions arise.  These conditions differ from UNIX
signals in that they are raised synchronously, via a regular
function call; and that a single condition can call several 
different functions.  

The system-defined conditions are:
\begin{description}
\item[CcdPROCESSOR\_BEGIN\_IDLE] Raised when the scheduler first
finds it has no messages to execute.  That is, this condition is
raised at the trailing edge of the processor utilization graph.
\item[CcdPROCESSOR\_STILL\_IDLE] Raised when the scheduler subsequently
finds it still has no messages to execute.  That is, this condition is
raised while the processor utilization graph is flat.
\item[CcdPROCESSOR\_BEGIN\_BUSY] Raised when a message first arrives
on an idle processor.  That is, raised on the rising edge of the
processor utilization graph.
\item[CcdPERIODIC] The scheduler attempts to raise this condition every
few milliseconds.  The scheduling for this and the other periodic conditions
is nonpreemptive, and hence may be delayed until the current entry point is 
finished.
\item[CcdPERIODIC\_10ms] Raised every 10ms (at 100Hz).
\item[CcdPERIODIC\_100ms] Raised every 100ms (at 10Hz).
\item[CcdPERIODIC\_1second] Raised once per second.
\item[CcdPERIODIC\_10second] Raised once every 10 seconds.
\item[CcdPERIODIC\_1minute] Raised once per minute.
\item[CcdPERIODIC\_10minute] Raised once every 10 minutes.
\item[CcdPERIODIC\_1hour] Raised once every hour.
\item[CcdPERIODIC\_12hour] Raised once every twelve hours.
\item[CcdPERIODIC\_1day] Raised once every day.

\item[CcdQUIESCENCE] Raised when the quiescence detection system
has determined that the system is quiescent.
\item[CcdSIGUSR1] Raised when the system receives the UNIX signal SIGUSR1.
Be aware that this condition is thus raised asynchronously, from
within a signal handler, and all the usual signal handler restrictions apply.
\item[CcdSIGUSR2] Raised when the system receives the UNIX signal SIGUSR2.
\item[CcdUSER] The system never raises this or any larger conditions.
They can be used by the user for application-specific use.  All conditions
from CcdUSER to CcdUSER+256 are so available.
\end{description}

\function{int CcdCallOnCondition(condnum,fnp,arg)}
\args{int condnum;}
\args{CcdVoidFn fnp;}
\args{void *arg;}

This call instructs the system to call the function indicated by the
function pointer {\tt fnp}, with the specified argument {\tt arg}, when the
condition indicated by {\tt condnum} is raised next. Multiple functions may
be registered for the same condition number.

\function{int CcdCallOnConditionKeep(condnum,fnp,arg)}
As above, but the association is permanent-- the given function will
be called again whenever this condition is raised.

Returns an index that may be used to cancel the association later.

\function{void CcdCancelCallOnCondition(int condnum, int idx)}
\function{void CcdCancelCallOnConditionKeep(int condnum, int idx)}
Delete the given index from the list of callbacks for
the given condition. The corresponding function will no longer be 
called when the condition is raised.
Note that it is illegal to call these two functions to cancel callbacks from within ccd callbacks.

\function{void CcdRaiseCondition(condNum)}
\args{int condNum;}

When this function is called, it invokes all the functions whose
pointers were registered for the \verb#condNum# via a {\em prior} call
to {\tt CcdCallOnCondition} or {\tt CcdCallOnConditionKeep}.  

\function{void CcdCallFnAfter(fnp, arg, msLater)}
\args{CcdVoidFn fnp;}
\args{void *arg;}
\args{unsigned int msLater;}

This call registers a function via a pointer to it, {\tt fnp},  that will be
called at least {\tt msLater} milliseconds later. 
The registered function {\tt fnp} is actually called the first time the
scheduler gets control after {\tt deltaT} milliseconds have elapsed. 

