Changeset 573

Timestamp:

May 3, 2004, 6:13:29 PM (22 years ago)

Author:

Paul Price

Message:

Added discussion of RHL's fix to psError to allow other
projects to add their own error codes.

File:

• trunk/doc/pslib/psLibSDRS.tex (modified) (5 diffs)

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.39 2004-04-28 00:27:24 price Exp $
+%%% $Id: psLibSDRS.tex,v 1.40 2004-05-04 04:13:29 price Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -897 +897 @@
 \hlabel{psErrorCodes}
 
-The type \code{psErrorCode} is defined by an auxiliary file, conventionally named
-\file{psErrorCodes.dat}. This file shall consist of a number of lines, each
-of the form:
-\begin{verbatim}
-NAME [ = value ] , STRING
-\end{verbatim}
-where \code{[ = value]} is optional, and no spaces are significant except in the
-STRING.  Comments extend from \code{#} to the end of the line (except that a
-\code{\#} shall be replaced by \code{#} and not taken to start a comment). For example,
+Both error codes for PSLib and error codes for projects that use PSLib
+may be registered.  In the former case, the error codes shall be
+registered on initialisation, whereas in the latter case, it is
+required to explicitly register.
+
+\paragraph{Registering error codes}
+
+An array of error codes may be registered with the PSLib error handler
+using a private function:
+
+\begin{verbatim}
+void p_psErrorRegister(const psErrorDescription *errors, ///< register a set of errors
+                       int nerror                        ///< number of errors
+    );
+\end{verbatim}
+
+Where the errors are represented internally as follows:
+\begin{verbatim}
+typedef struct {
+    psErrorCode code;                  // An error code
+    char *descrip;                     // the associated description
+} psErrorDescription;
+\end{verbatim}
+
+Projects wishing to employ the PSLib error handler should define
+a function,
+\begin{verbatim}
+void prefixErrorRegister(void);
+\end{verbatim}
+where \code{prefix} is particular to the project.  For example, PSLib
+should have a function,
+\begin{verbatim}
+void psErrorRegister(void);
+\end{verbatim}
+In this case (i.e., error codes for PSLib), the function should be
+called upon initialisation.  As another example, MOPS should implement
+a function,
+\begin{verbatim}
+void mopsErrorRegister(void);
+\end{verbatim}
+which would be called explicitly when MOPS utilises PSLib.
+
+It is left to the external project to produce the appropriate
+\code{prefixErrorRegister()}, but they may find helpful the
+implementation discussed below for use in PSLib.
+
+There is a clear need to coordinate the choice of error numbers.  It
+is expected that error code ranges for different projects shall be
+managed by the Project Office.
+
+\paragraph{Error Codes for PSLib}
+
+For ease of maintenance, error codes for PSLib shall be defined by an
+auxiliary file, conventionally named \file{psErrorCodes.dat}.  The
+format of this file shall consist of a number of lines, each of the
+form:
+\begin{verbatim}
+NAME [ = value ][,] STRING
+\end{verbatim}
+where \code{[ = value]} and the comma are optional, and no spaces are
+significant except in the STRING.  Comments extend from \code{#} to
+the end of the line (except that a \code{\#} shall be replaced by
+\code{#} and not taken to start a comment). For example,
 \begin{verbatim}
 #
@@ -913 +967 @@
 BASE = 256,             first value we use; should avoid errno conflicts
 UNKNOWN,                unknown error
+# This is a comment, and is ignored.
 IO,                     I/O error
 BADFREE,                bad argument to psFree()
@@ -919 +974 @@
 The values \code{NONE = 0} and {UNKNOWN} must be present.
 
-The \PS{} Makefiles shall
-generate two files, \file{psErrorCodes.h} and
-\file{psErrorCodes.c} from the input file \file{psErrorCodes.dat}.
-\file{psErrorCodes.h} shall define an enumerated type
-\code{psErrorCode} with elements \code{PS_ERR_NAME} and values as specified
-in \file{psErrorCodes.dat}, e.g.
+A script, called from the Makefiles, shall generate two files,
+\file{psErrorCodes.h} and \file{psErrorCodes.c} from the input file
+\file{psErrorCodes.dat}.  \file{psErrorCodes.h} shall define an
+enumerated type \code{psErrorCode} with elements \code{PS_ERR_NAME}
+and values as specified in \file{psErrorCodes.dat}, e.g.
 \begin{verbatim}
 #if !defined(PS_ERROR_CODES_H)
@@ -938 +992 @@
     PS_ERR_N_ERR_CLASSES,
 } psErrorCode;
-
 #endif
 \end{verbatim}
+
 Any \code{errorCode}s less then or equal to \code{PS_ERR_BASE} shall be taken
 to be valid values of \code{errno}.
 
-The implementation may add extra fields (e.g. \code{PS_ERR_N_ERR_CLASSES}).
-
-The latter shall be of the form
-\begin{verbatim}
-static struct {
-    psErrorCode code;
-    char *descrip;
-} errorStrings[] = {
-    { PS_ERR_NONE, "not an error; must be 0"},
-    { PS_ERR_BASE, "first value we use; should avoid errno conflicts"},
-    { PS_ERR_UNKNOWN, "unknown error"},
-    { PS_ERR_IO, "I/O error"},
-    { PS_ERR_BADFREE, "bad argument to psFree()"},
-    { PS_ERR_MEMORY_CORRUPTION, "memory corruption detected"},
-    { PS_ERR_N_ERR_CLASSES, NULL},
-};
-\end{verbatim}
+The implementation may add extra fields (e.g., \code{PS_ERR_N_ERR_CLASSES}).
+
+\file{psErrorCodes.c} shall define the necessary function to register
+the error codes.
 
 \subsubsection{Example}