flightgear/Docs/Time/Events/Events.tex

%
% `Events.tex' -- describes the FG Event Manager
%
%  Written by Curtis Olson.  Started December, 1997.
%
% $Id$
%------------------------------------------------------------------------


\documentclass[12pt]{article}

\usepackage{anysize}
\papersize{11in}{8.5in}
\marginsize{1in}{1in}{1in}{1in}

\usepackage{amsmath}

\usepackage{epsfig}

\usepackage{setspace}
\onehalfspacing

\usepackage{url}


\begin{document}


\title{
  Flight Gear Periodic Event Manager and Scheduler
}


\author{
    Curtis L. Olson\\ 
    (\texttt{curt@me.umn.edu})
}


\maketitle


\section{Introduction}

Many tasks within the simulator need to only run periodically.  These
are typically tasks that calculate values that don't change
significantly in 1/60th of a second, but instead change noticeably on
the order of seconds, minutes, or hours.

Running these tasks every iteration would needless degrade
performance.  Instead, we would like to spread these out over time to
minimize the impact they might have on frame rates, and minimize the
chance of pauses and hesitations.

\section{Overview}

The goal of the event manager is to provide a way for events to be run
periodically, and to spread this load out so that the processing time
spent at any particular iteration is minimized.

The scheduler consists of two parts.  The first part is simply a list
of registered events along with any management information associated
with that event.  The second part is a run queue.  When events are
triggered, they are placed in the run queue.  The system executes only
one pending event per iteration in order to balance the load.

\section{The Events List}

\subsection{Event List Structure}

All registered events are maintained in a list.  Currently, this list
is simply an array of event structures.  Each event structure stores
the following information.

\begin{itemize}
  \item An ASCII description or event identifier.  This is used when
    outputting event statistics.

  \item A pointer to the event function.

  \item An event status flag.  The flag marks the process as ready to
    run, queued in the run queue, or suspended from eligibility to
    run.
    
  \item A time interval specifying how often to schedule and run this
    event.
                      
  \item The absolute time this event was last run.
  
  \item The next absolute time this event is scheduled to run.
    
  \item The cumulative run time for this process (in ms.)
    
  \item The least time consumed by a single run of this event (in ms.)

  \item The most time consumed by a single run of this event (in ms.)

  \item The number of times this event has been run.
\end{itemize}

\subsection{Event List Operation}

To use the event list, you must first initialize it by calling
\texttt{fgEventInit()}.  

Once the list has been initialized, you can register events by calling
\texttt{fgEventRegister()}.  A typical usage might be:
\texttt{fgEventRegister(``fgUpdateWeather()'', fgUpdateWeather,
  FG\_EVENT\_READY, 60000)}.  This tells the event manager to schedule
and run the event, \texttt{fgUpdateWeather()}, every 60 seconds.  The
first field is an ASCII description of the function, the second field
is a pointer to the function, the third field is the status flag, and
the last field is the time interval.  Event functions should return
\texttt{void} and accept no parameters.  The status flag can set to
either \texttt{FG\_EVENT\_SUSP}, \texttt{FG\_EVENT\_READY}, or
\texttt{FG\_EVENT\_QUEUED}.  \texttt{FG\_EVENT\_SUSP} means register
the event, but never schedule it to run.  \texttt{FG\_EVENT\_READY}
means register the event and schedule and run it normally.
\texttt{FG\_EVENT\_QUEUED} is mostly used internally so that an event
will never have more than one entry in the run queue.

Finally, in your main loop, you must add a call to
\texttt{fgEventProcess()} to run it every iteration.  This routine
will schedule all pending events (push them onto the run queue) and
then execute the first thing in the run queue.

\section{The Run Queue}

The run queue is a very simple queue who's elements are just a pointer
to an event list element.  When an event needs to be scheduled, a
pointer to that event is pushed onto the back of the queue.  Each time
\texttt{fgEventProcess()} is called, the first element on the run
queue will be executed.

\section{Profiling Events}

As stated before, each event record contains simple event statistics
such as the total time spent running this event, the quickest run, the
slowest run, and the total number of times run.  We can output the
list of events along with these statistics in order to determine if any of
them are consuming an excessive amount of time, or if there is any
chance that a particular event could run slow enough to be responsible
for a perceived hesitation or pause in the flow of the simulation.

\end{document}


%------------------------------------------------------------------------