148 lines
4.8 KiB
TeX
148 lines
4.8 KiB
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}
|
|
|
|
|
|
%------------------------------------------------------------------------
|