Changeset 2371

Timestamp:

Nov 15, 2004, 12:22:53 PM (22 years ago)

Author:

Paul Price

Message:

Added statement on use of restrict, and on use of persistent memory.

Location:

trunk/doc/pslib

Files:

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

trunk/doc/pslib/ChangeLogSDRS.tex

@@ -1 @@
-%%% $Id: ChangeLogSDRS.tex,v 1.44 2004-11-15 20:20:30 price Exp $
+%%% $Id: ChangeLogSDRS.tex,v 1.45 2004-11-15 22:22:48 price Exp $
 
 \subsection{Changes from version 00 to version 01}
@@ -373 +373 @@
 \item Removed errors from \code{psVectorFitSpline1D}.
 \item \code{psTraceReset} is to free memory used by \code{psTrace}.
+\item Added requirement on use of persistent memory --- any use of
+  persistent memory shall provide a function that frees the persistent
+  memory.
+\item Added statement on use of \code{restrict}.
 \end{itemize}
 

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.150 2004-11-15 20:19:46 price Exp $
+%%% $Id: psLibSDRS.tex,v 1.151 2004-11-15 22:22:53 price Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -158 +158 @@
 convenience to the user.
 
+\subsection{Use of \code{restrict}}
+
+The \code{restrict} type qualifier in C99 indicates to the compiler
+that the memory pointed to by a particular pointer is not also pointed
+to by some other pointer.  This allows the compiler to optimise the
+code, based on the fact that aliasing is not an issue.  However, the
+compiler does not check the accuracy of the assumption on which the
+optimisation is made, which can lead to data corruption.
+
+Due to the large number of cross-links in psLib (e.g., the metadata
+container keeps two pointers to the data), the assumption behind the
+use of \code{restrict} generally will not hold.  Correspondingly, use
+of \code{restrict} should be kept to a minimum; it should only be
+employed where necessary, and where the assumption will hold.
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -363 +378 @@
 only provided if the code is compiled with the preprocessor variable
 \code{PS_MEM_DEBUG} defined.
+
+\paragraph{Use of Persistent Memory}
+
+The \code{persistent} member of the \code{psMemBlock} is provided as a
+convenience to the end-user of psLib --- it allows him to check for
+memory leaks in his own code, without going to the trouble of freeing
+memory allocated for psLib core functions.  It also allows the use of
+psLib core functions (e.g., \code{psLogMsg, psTrace}) within the
+function that is called by \code{psMemCheckLeaks}, without the memory
+allocated by those psLib core functions being identified as a leak.
+
+For these reasons, the \code{persistant} feature should only be used
+as necessary.  In order to allow proper testing of psLib, all
+components that employ any \code{persistent} memory shall provide a
+function that frees all of its \code{persistent} memory (and only that
+persistent memory that belongs to that component).
 
 \subsubsection{APIs for Allocating and Freeing}