(*
 * Title:    alarm.h
 * Purpose:  alarm facilities for wimp programs, using non-busy waiting
 *
 *)

#ifndef __alarm_h
#define __alarm_h

type alarm_handler = ^procedure handler(called_at : integer;
                                        handle : pointer);


(* ----------------------------- alarm_init --------------------------------
 * Description:   Initialise the alarm system. 
 * 
 * Parameters:    void
 * Returns:       void.
 * Other Info:    If this call is made more than once, then any pending
 *                alarms are cancelled. 
 *
 *)
procedure alarm_init; extern;


(* ----------------------------- alarm_timenow -----------------------------
 * Description:   Reports the current monotonic time.
 * 
 * Parameters:    void
 * Returns:       the current monotonic time.
 * Other Info:    none.
 *
 *)
procedure alarm_timenow; extern;


(* --------------------------- alarm_timedifference ------------------------
 * Description:   Returns difference between two times.
 *
 * Parameters:    int t1 -- the earlier time
 *                int t2 -- the later time
 * Returns:       difference between t1 and t2.
 * Other Info:    Times are as in SWI OS_ReadMonotonicTime. Deals with wrap
 *                round of timer.
 *
 *)
function alarm_timedifference(t1, t2 : integer) : integer; extern;


(* ------------------------------ alarm_set --------------------------------
 * Description:   Set an alarm at the given time.
 *
 * Parameters:    int at -- time at which alarm should occur
 *                alarm_handler proc -- function to be called at alarm time
 *                void *handle -- caller-supplied handle to be passed to 
 *                                function
 * Returns:       void.
 * Other Info:    The supplied function is called before passing the event 
 *                on to any idle event claimer windows. 
 *                "at" is in terms of the monotonic centi-second timer.
 *                The supplied function is passed the time at which it was
 *                called. If you have enabled idle events, then these are
 *                still returned to you; if not, RISC_OSlib uses idle events
 *                internally to implement alarm calls (using non-busy
 *                waiting via wimp_pollidle()).
 *
 *)
procedure alarm_set(at : integer;
                proc : alarm_handler;
                handle : pointer); extern;


(* ----------------------------- alarm_remove ------------------------------
 * Description:   Removes an alarm which was set for a given time with a
 *                given handle.
 *
 * Parameters:    int at -- the time at which the alarm was to be made
 *                void *handle -- the given handle
 * Returns:       void.
 * Other Info:    If no such alarm exists this call has no effect.
 *
 *)
procedure alarm_remove(at : integer; handle : pointer); extern;


(* --------------------------- alarm_removeall -----------------------------
 * Description:   Removes all alarms which have a given handle.
 *
 * Parameters:    void *handle -- the handle to search for.
 * Returns:       void.
 * Other Info:    none.
 *
 *)
procedure alarm_removeall(handle : pointer); extern;


(* ---------------------------- alarm_anypending ---------------------------
 * Description:   Returns whether an alarm is pending with a given handle
 *
 * Parameters:    void *handle -- the handle.
 * Returns:       TRUE if there are any pending alarms for this handle.
 * Other Info:    none.
 *
 *)
function alarm_anypending(handle : pointer) : boolean; extern;


(* ----------------------------- alarm_next --------------------------------
 * Description:   Informs caller whether an alarm is pending and, if so, for
 *                when it is.
 *
 * Parameters:    int *result -- time for which alarm is pending
 * Returns:       TRUE if an alarm is pending.
 * Other Info:    This should be used by polling loops (if you use the
 *                standard "while(TRUE) event_process();" loop then this is
 *                done for you). If a polling loop finds that an alarm is set
 *                it should use wimp_pollidle(with earliest time set to
 *                *result of alarm_next()) rather than wimp_poll to do its
 *                polling.  If you handle idle events yourself, then your
 *                handler should use call_next to call the next alarm
 *                function upon receiving an idle event (ie. wimp_ENULL).
 *
 *)
function alarm_next(var result : integer) : boolean; extern;


(* ---------------------------- alarm_callnext -----------------------------
 * Description:   Calls the next alarm handler function.
 *
 * Parameters:    void
 * Returns:       void.
 * Other Info:    This is done for you if you use event_process() to do your
 *                polling (or even if you sink down as far as using wimpt
 *                for polling).
 *
 *)
procedure alarm_callnext; extern;

#endif

(* end of alarm.h *)
