Changeset 4368 for trunk/doc/pslib/psLibSDRS.tex

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

File:

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

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}