Changeset 1925

Timestamp:

Sep 28, 2004, 4:32:24 PM (22 years ago)

Author:

Paul Price

Message:

"persistent" in psMemBlock, changes to psListRemove.

Location:

trunk/doc/pslib

Files:

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

trunk/doc/pslib/ChangeLogSDRS.tex

@@ -306 +306 @@
 \item Added configuration file grammar.
 \item Added explanation of \code{psArray *coords} in
-  \code{psMinimizeLMFunc}, and changed \code{psMatrix} to \code{psImage}
-  in response to bug 191.
+  \code{psMinimizeLMFunc}, and changed \code{psMatrix} to
+  \code{psImage} in response to bug 191.
 \item Added \code{psTimeTable}.
 \item \code{psLibInit} altered to load \code{psTime} configuration
@@ -313 +313 @@
 \item Reworked \code{psList} (including addition of new functions) to
   support multiple iterators.
-\item Specified return value for \code{psImageOverlaySection} is the number
-  of pixels overlaid.
+\item Specified return value for \code{psImageOverlaySection} is the
+  number of pixels overlaid.
+\item Added \code{persistent} to \code{psMemBlock}, along with
+  additional specification of behaviour of \code{psMemCheckLeaks}.
+\item Removed \code{psListRemoveNext} and \code{psListRemoveAfter}.
+  Removing an item pointed to by an iterator doesn't cause an error.
+
 \end{itemize}

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.124 2004-09-28 01:47:46 price Exp $
+%%% $Id: psLibSDRS.tex,v 1.125 2004-09-29 02:32:24 price Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -307 +307 @@
     pthread_mutex_t   refCounterMutex;  ///< mutex to ensure exclusive access to reference counter
     psReferenceCount refCounter;        ///< how many times pointer is referenced
+    bool persistent;                    ///< marks if non-user persistent data like error stack, etc.
     const void* endblock;               ///< initialised to p_psMEMMAGIC
 } psMemBlock;
@@ -342 +343 @@
 The element \code{refCounterMutex} is a mutex used to limit access to
 the reference counter (below) to a single thread at a time.
+
+The element \code{persistent} indicates if the memory is to be used by
+some non-user persistent data.  This allows memory marked as
+\code{persistent} to be ignored when identifing memory leaks with
+\code{psMemCheckLeaks}.  Private functions shall be provided to test
+and set the value of \code{persistent}.
 
 The \code{psMemBlock} structure element \code{refCounter} is provided
@@ -572 +579 @@
 %
 \begin{verbatim}
-int psMemCheckLeaks(psMemoryId id0, psMemBlock ***array, FILE *fd);
+int psMemCheckLeaks(psMemoryId id0, psMemBlock ***array, FILE *fd, bool persistence);
 int psMemCheckCorruption(bool abort_on_error);
 \end{verbatim}
@@ -593 +600 @@
 of each block that has been allocated but not freed is written to that
 file descriptor.
+
+If \code{persistence} is \code{false}, then only those
+\code{psMemBlock}s not marked as \code{persistent} shall be considered
+as memory leaks.  If \code{persistence} is \code{true}, then all
+\code{psMemBlocks} shall be considered as memory leaks.
 
 The routine \code{psMemCheckCorruption} checks the entire heap for
@@ -975 +987 @@
 returns the error code.
 \begin{verbatim}
-psErrorCode psError(const char *name, psErrorCode code, bool new, const char *fmt, ...);
-\end{verbatim}
-
-The \code{name} is of the form \code{aaa.bbb.ccc} and identifies the
-component raising the error.  The \code{code} is an enumerated type
-which lists the possible \textit{classes} of errors
-(e.g. \code{PS_ERR_IO}) that \PS{} code can generate (see section
-\ref{psErrorCodes}). The \code{new} argument takes a boolean which, if
-\code{TRUE} specifies that the error was set initially at this
-location, and if \code{FALSE} specifies that an error was passed to
-this location.  Raising new error should clear the error stack.  The
-final required argument, \code{fmt}, is a \code{printf}-style format
-that is passed to \code{psLogMsgV} with code \code{PS_LOG_ERROR}.  The
-result of a call to \code{psError} must be to push an error onto a
-stack; this stack is cleared if \code{new} is true, or by a call to
+psErrorCode p_psError(const char *file, int lineno, psErrorCode code, bool new, const char *fmt, ...);
+#define psError(code, new, fmt, ...) psError(__FILE__, __LINE__, code, new, fmt, __VA_ARGS__)
+\end{verbatim}
+
+\code{psError} is a macro definition that allows the function and line
+number to be inputted to a private function, \code{p_psError}.  The
+\code{code} is an enumerated type which lists the possible
+\textit{classes} of errors (e.g. \code{PS_ERR_IO}) that \PS{} code can
+generate (see section \ref{psErrorCodes}). The \code{new} argument
+takes a boolean which, if \code{TRUE} specifies that the error was set
+initially at this location, and if \code{FALSE} specifies that an
+error was passed to this location.  Raising new error should clear the
+error stack.  The final required argument, \code{fmt}, is a
+\code{printf}-style format that is passed to \code{psLogMsgV} with
+code \code{PS_LOG_ERROR}, and component equal to the concatenation of
+the file name and the line number, separated by a colon.  The result
+of a call to \code{psError} must be to push an error onto a stack;
+this stack is cleared if \code{new} is true, or by a call to
 \code{psErrorClear}.
 
@@ -1573 +1588 @@
 bool psListRemove(psList *list, int location)
 bool psListRemoveData(psList *list, void *data);
-bool psListRemoveAfter(psListIterator *iterator);
-bool psListRemoveBefore(psListIterator *iterator);
 \end{verbatim}
 A data item may be removed from the list with these functions.  For
@@ -1583 +1596 @@
 matching the pointer value with \code{void *data}.  The functions
 return a value of \code{true} if the operation was successful, and
-\code{false} otherwise.  The other two functions,
-\code{psListRemoveBefore} and \code{psListRemoveAfter} remove the item
-before or after (respectively) the iteration cursor.  In all cases, if
-any iterators are currently pointing at the item to be removed, or the
-item to be removed is not on the list, an error shall be generated,
-the item shall not be removed, and the function shall return
+\code{false} otherwise.  In both cases, if any iterators are currently
+pointing at the item to be removed, the item shall be removed and
+those iterators pointing at it shall be moved to the next, and the
+function shall return \code{true}.  If the item to be removed is not
+on the list, an error shall be generated and the function shall return
 \code{false}.
-
 
 \begin{verbatim}