Changeset 5538

Timestamp:

Nov 17, 2005, 3:35:53 PM (21 years ago)

Author:

Paul Price

Message:

Added requirement on dynamic setting of mutex locks: psMemThreadSafety.

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.180 2005-11-18 00:27:19 price Exp $
+%%% $Id: ChangeLogSDRS.tex,v 1.181 2005-11-18 01:35:49 price Exp $
 
 \subsection{Changes from version 00 to version 01}
@@ -827 +827 @@
 \item Updated \code{psImageTransform} to use \code{psPixels} for
   \code{blankPixels} instead of a \code{psArray}.
-\end{itemize}
+\item Added requirement on dynamic setting of mutex locks:
+  \code{psMemThreadSafety} (see bug 586).
+\end{itemize}

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.356 2005-11-18 00:26:19 price Exp $
+%%% $Id: psLibSDRS.tex,v 1.357 2005-11-18 01:35:53 price Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -163 +163 @@
   (Sections~\ref{sec:memory} \&~\ref{sec:errors}), must be written to
   be thread-safe, since we cannot risk this crucial area being
-  unstable.
+  unstable.  However, this can have a large impact on the efficiency
+  of the code, and so we specify that this behaviour may be activated
+  and deactivated dynamically.  The default behaviour, however, will
+  be thread-safety, since it is more important to err on the side of
+  being safe rather than efficient.  
 \item Re-entrant versions of system calls and external library
   functions should be used.  We expect that these cases are
@@ -794 +798 @@
 in the valid range and must correspond to the address of the
 \code{psMemBlock}).
+
+\subsubsection{Thread safety}
+
+Locking a mutex is an expensive operation that can dramatically impact
+the efficiency of a program for the worse.  When the user is not
+concerned with multiple threads, this is a needless waste, and so we
+specify that the thread safety in the memory management system may
+be deactivated (and activated) dynamically.
+
+\begin{prototype}
+bool psMemThreadSafety(bool safe);
+\end{prototype}
+
+\code{psMemThreadSafety} shall turn on thread safety in the memory
+management functions if \code{safe} is \code{true}, and deactivate all
+mutex locking in the memory management functions if \code{safe} is
+\code{false}.  The function shall return the previous value of the
+thread safety.
+
+Note that the default behaviour of the library shall be for the
+locking to be performed.
 
 \subsubsection{Relation of Memory Management to Structures}