Changeset 4368

Timestamp:

Jun 23, 2005, 11:19:45 AM (21 years ago)

Author:

Paul Price

Message:

Clarified policy on signed/unsigned for memory allocation; psAlloc checks the allocation size against PS_MEM_LIMIT

Location:

trunk/doc/pslib

Files:

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

trunk/doc/pslib/ChangeLogSDRS.tex

@@ -1 @@
-%%% $Id: ChangeLogSDRS.tex,v 1.151 2005-06-23 03:06:32 price Exp $
+%%% $Id: ChangeLogSDRS.tex,v 1.152 2005-06-23 21:19:45 price Exp $
 
 \subsection{Changes from version 00 to version 01}
@@ -736 +736 @@
 \item Added \code{psArrayElementsFree} (already implemented).
 \item \code{psMask} changed to \code{psMaskType} (more clear).
-\item Use the \code{region} in \code{psImageTransform} to set the size of the output image (bug 453).
-\item \code{list} in \code{psListIteratorAlloc} is not const (bug 455).
-\end{itemize}
+\item Use the \code{region} in \code{psImageTransform} to set the size
+  of the output image (bug 453).
+\item \code{list} in \code{psListIteratorAlloc} is not const (bug
+  455).
+\item Clarified policy on signed/unsigned for memory allocation;
+  \code{psAlloc} checks the allocation size against
+  \code{PS_MEM_LIMIT}.
+\end{itemize}

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.294 2005-06-23 03:06:32 price Exp $
+%%% $Id: psLibSDRS.tex,v 1.295 2005-06-23 21:19:45 price Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -547 +547 @@
 \code{NULL}.  If no free function is set, \code{psMemGetDeallocator}
 shall return \code{NULL}.
+
+\paragraph{Negative allocations}
+
+Note that we have specified that the memory size is unsigned
+(\code{size_t}), so that we can address the full range of memory that
+the architecture will allow, and to match the behaviour of the system
+\code{malloc}.  This creates the potential for problems if a negative
+value is inadvertently passed to \code{psAlloc} --- it will be
+interpreted as a very large positive value.  To guard against this, we
+specify that \code{psAlloc} must check that the allocation is less
+than \code{PS_MEM_LIMIT} (a preprocessor variable).
+
+For array-like collections (specifically, \code{psArray},
+\code{psVector}, and \code{psImage}) we allow the user to refer to a
+negative index to mean address from the end.  Consequently, the number
+of elements in structures should be signed.  It is the responsibility
+of these structure allocators (e.g., \code{psArrayAlloc}) to check
+that the requested number of elements is not negative (calling
+\code{psAbort} otherwise).  All other allocators shall simply use
+size_t where the number of elements is needed (saving the trouble of
+checking before passing to psAlloc).
 
 \subsubsection{Callback Routines}