Changeset 4711

Timestamp:

Aug 4, 2005, 5:51:16 PM (21 years ago)

Author:

Paul Price

Message:

Adding psTimer, changing psLibInit to psTimeInit, adding psArgument functions

Location:

trunk/doc/pslib

Files:

• ChangeLogSDRS.tex (modified) (2 diffs)
• psLibSDRS.tex (modified) (7 diffs)

trunk/doc/pslib/ChangeLogSDRS.tex

@@ -1 @@
-%%% $Id: ChangeLogSDRS.tex,v 1.161 2005-07-22 22:39:21 price Exp $
+%%% $Id: ChangeLogSDRS.tex,v 1.162 2005-08-05 03:51:16 price Exp $
 
 \subsection{Changes from version 00 to version 01}
@@ -760 +760 @@
 \item \code{psPixelCoord} now contains floats.
 \item \code{psImageSlice} uses \code{psPixels} to output coordinates.
-\end{itemize}
-
+\item Added \code{psTimer} functions (prototypes by EAM).
+\item \code{psLibInit} and \code{psLibCleanup} changed to
+  \code{psTimeInitialize} and \code{psTimeFinalize}.  Calls to
+  functions that require the time tables before calling
+  \code{psTimeInitialize} shall produce an error.
+\item Added \code{psArgument} functions to provide simple argument
+  handling.
+\end{itemize}
+

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.321 2005-07-22 22:36:33 price Exp $
+%%% $Id: psLibSDRS.tex,v 1.322 2005-08-05 03:51:16 price Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -271 +271 @@
 \subsection{Initialization}
 
-PSLib may be initialized by calling \code{psLibInit} by the user
-before use.  This enables the library to perform the following tasks
-that are required before general use:
-\begin{itemize}
-\item Set the error codes for PSLib.
-\item Read the \code{psTime} configuration file (\code{timeConfig})
-  and set up the appropriate \code{psTimeTable}s and predictions.
-\end{itemize}
-
-The prototype is:
-\begin{prototype}
-void psLibInit(const char *timeConfig);
-\end{prototype}
-
-\code{timeConfig} specifies the filename of the configuration file
-for \code{psTime} metadata.
-
-\subsection{Finalization}
-
-\begin{prototype}
-void psLibCleanup(void);
-\end{prototype}
-
-\code{psLibCleanup} shall free memory that was allocated by
-\code{psLibInit}, allowing a subsequent search for leaked memory (even
-memory marked as \code{persistent}).
+Before certain \code{psTime} functions can be employed, the user must
+call \code{psTimeInitialize}.
 
 \subsection{Memory Management}
@@ -1628 +1604 @@
 
 
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \subsection{Abort}
@@ -1639 +1615 @@
 \end{prototype}
 
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\subsection{Command-line arguments}
+
+The following functions are provided to aid parsing of command-line
+arguments:
+
+\begin{prototype}
+int psArgumentGet(int argc, char **argv, const char *arg);
+bool psArgumentRemove(int argnum, int *argc, char **argv);
+\end{prototype}
+
+\code{psArgumentGet} shall return the index of the element in the
+argument list, \code{argv} with number of entries \code{argc}, that
+matches the specified argument, \code{arg}, or zero if there is no
+match.
+
+\code{psArgumentRemove} shall remove from the argument list
+(\code{argv} with number of entries \code{argc}) the argument whose
+index is \code{argnum}.  The number of entries in the argument list
+shall be decremented.  The function shall return \code{true} if the
+\code{argnum} is in the argument list, and \code{false} otherwise.
+
+\begin{prototype}
+int psArgumentVerbosity(int *argc, char **argv);
+\end{prototype}
+
+\code{psArgumentVebosity} shall implement the various verbosity
+controls under the following guidelines:
+\begin{itemize}
+\item \code{-v} switch shall set the log level to 3.
+\item \code{-vv} switch shall set the log level to 4.
+\item \code{-vvv} switch shall set the log level to 5.
+\item \code{-logfmt someFormat} switch shall set the log format to
+  \code{someFormat}.
+\item \code{-trace facility level} switch shall set the trace level
+  for the specified \code{facility} to the specified \code{level}.
+\item \code{-trace-levels} switch shall print the trace levels as
+  currently set.
+\end{itemize}
+
+The above arguments shall be removed from the argument list as they
+are processed.  The function shall return the resultant logging level.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \pagebreak 
@@ -5730 +5750 @@
 track the time system being represented.
 
+\subsubsection{Initialization and Finalization}
+
+The conversions between various time standards, and the polar motion
+requires importing external data (``time tables''), the locations of
+which are specified in a configuration file.
+
+\begin{prototype}
+void psTimeInitialize(const char *timeConfig);
+\end{prototype}
+
+\code{psTimeInitialize} shall read the \code{psTime} configuration
+file (\code{timeConfig}) and set up the appropriate
+\code{psTimeTable}s and predictions.
+
+{\bf Calls to \code{psTime} functions that require the time tables
+before calling \code{psTimeInitialize} shall result in an error.}
+
+\begin{prototype}
+void psTimeFinalize(void);
+\end{prototype}
+
+\code{psTimeFinalize} shall free memory that was allocated by
+\code{psTime} functions, allowing a subsequent search for leaked
+memory (even memory marked as \code{persistent}).
+
 \subsubsection{Data Types}
 
@@ -5952 +5997 @@
 and ``to'' dates of applicability will be specified through metadata
 (\S\ref{sec:timeMetadata}).
+
+{\bf Calls to \code{psTime} functions that require the time tables
+before calling \code{psTimeInitialize} shall result in an error.}
 
 When a value is required, the tables shall shall be checked in
@@ -6017 +6065 @@
 A series of test inputs is contained in \S\ref{sec:timetest}.
 
+\subsection{Timers}
+
+It is useful to be able to time an operation.  For this purpose, we specify
+the following:
+
+\begin{prototype}
+bool psTimerStart(char *name);
+psF64 psTimerMark(char *name);
+psF64 psTimerStop(void);
+\end{prototype}
+
+\code{psTimerStart} shall store the current time in a \code{psHash} of
+timers, under the supplied \code{name}.  \code{psTimerMark} shall
+return the elapsed time, in seconds, for the timer specified by
+\code{name}.  \code{psTimerStop} shall free all memory associated with
+the timers, so that no memory is leaked, and return the maximum time
+expended.
+
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%