Changeset 179 for trunk/doc/draft/utils.tex

Timestamp:

Mar 9, 2004, 3:07:27 PM (22 years ago)

Author:

rhl

Message:

Updated

File:

• trunk/doc/draft/utils.tex (modified) (23 diffs)

trunk/doc/draft/utils.tex

@@ -58 +58 @@
 The \PS{} software system will need a level of memory management
 placed between the operating system (malloc/free) and the high level
-routines (e.g. \code{psMetaDataNew}).
+routines (e.g. \code{psMetaDataAlloc}).
 
 This layer is in addition to the possibility that specific heavily
 used data types may need their own special-purpose memory managers;
 but as we have specified that all user-level objects be allocated via
-\code{typeNew/typeDel} functions, we will easily be able to
+\code{typeAlloc/typeFree} functions, we will easily be able to
 implement such functionality without impacting on the facilities
 described here.
@@ -69 +69 @@
 All of the memory management APIs should be provided in a header file
 \file{psMemory.h} which is included by \file{psUtils.h}.
-
-\textit{Do we want to rename \code{psAlloc} to \code{psNew} and
-  \code{psFree} to \code{psDel}? Or is it too late? XXX}
 
 \subsection{Rationale}
@@ -92 +89 @@
   We need to provide a mechanism for tracking and fixing memory
   leaks.  While it is possible to do this by linking with external
-  libraries (XXX reference), it is convenient to do so within the
+  libraries (\tbd{reference}), it is convenient to do so within the
   \PS{} framework.
 
@@ -376 +373 @@
 } psSimple;
 
-psSimple *psSimpleNew(const char *name, int val)
+psSimple *psSimpleAlloc(const char *name, int val)
 {
     psSimple *simp = psAlloc(sizeof(psSimple));
@@ -385 +382 @@
 }
 
-void psSimpleDel(psSimple *simp)
+void psSimpleFree(psSimple *simp)
 {
     if (simp == NULL) { return; }
@@ -411 +408 @@
 \goodbreak
 \begin{verbatim}
-simp = psSimpleNew("RHL", 0);
+simp = psSimpleAlloc("RHL", 0);
 psDlistAppend(list1, psMemIncrRefCounter(simp));
 psDlistAppend(list2, psMemIncrRefCounter(simp));
-psSimpleDel(simp);
+psSimpleFree(simp);
 \end{verbatim}
 
@@ -447 +444 @@
                     int level);         // desired trace level
 int psGetTraceLevel(const char *name);  // facilty of interest
+
+void psTraceReset(void);                // turn off all tracing, and free trace's allocated memory
 
 void psPrintTraceLevels(void);          // print trace levels
@@ -513 +512 @@
       within the functions that implement \file{psTrace.h}
       or \file{psMemory.h} systems.
+
+    \item
+      \code{psTraceReset} shall reset all tracing to the state that it
+      had at program initiation, including freeing any memory that the
+      tracing subsystem may have allocated.
 \end{itemize}
 
@@ -581 +585 @@
 
 int psSetLogDestination(int dest);
+void psSetLogFormat(const char *fmt);
+
 int psSetLogLevel(int level);
   \end{verbatim}
@@ -634 +640 @@
 write to \code{stderr} and \code{stdout} respectively.
 
-\section{The Pan-STARRS \texttt{psDlist} doubly-linked list type}
+The fields included in the log message may be controlled using \code{psSetLogFormat} which
+expects a string consisting of the letters \code{H} (host), \code{L} (level), \code{M} (message),
+\code{N} (name), and \code{T} (time).  The default is \code{HLMNT}.
+
+\section{The Pan-STARRS \code{psDlist} doubly-linked list type}
 \hlabel{psDlist}
 
@@ -667 +677 @@
 
 \begin{verbatim}
-psDlist *psDlistNew(void *data);        // initial data item; may be NULL
-
-void psDlistDel(psDlist *list,          // list to destroy
-                void (*elemDel)(void *)); // destructor for list data, or NULL
+psDlist *psDlistAlloc(void *data);        // initial data item; may be NULL
+
+void psDlistFree(psDlist *list,          // list to destroy
+                void (*elemFree)(void *)); // destructor for list data, or NULL
 
 /*
@@ -702 +712 @@
 their reference counter.
 
-If \code{psDlistDel}'s argument \code{elemDel} is NULL, the
+If \code{psDlistFree}'s argument \code{elemFree} is NULL, the
 list should be deleted, but not the elements on it (although their
 \code{refcounter}'s should be decremented).
 
-The \code{psDlistGet} routine may be used to provide an iterator. The
-call \code{psDlistGet(list, psDlistHead)} returns the data from the
-head link of the list, but also sets the iteration cursor to the head.
-A seried of calls to \code{psDlistGet(list, psDlistNext)} return the
-elements of the list in order (you may also use \code{psDlistTail} and
-\code{psDlistPrev} to traverse the list backwards).
+Iteration over all elements of the list is provided by the functions:
+\begin{verbatim}
+void psDlistSetIterator(psDlist *list, int where, int which);
+void *psDlistGetNext(psDlist *list, int which);
+void *psDlistGetPrev(psDlist *list, int which);
+\end{verbatim}
+in which the \code{where} argument must be \code{PS_DLIST_HEAD} or \code{PS_DLIST_TAIL},
+to start at the head or tail of the list, and \code{psDlistGetNext} and \code{psDlistGetPrev}
+return the next/previous element. The argument \code{which} identifies which of potentially
+many iteration cursors should be used; it must currently always be \code{0}.
 
 Explicit traversal of the list using the \code{psDlistElem}'s
@@ -746 +760 @@
 with associated constructors and a destructor:
 \begin{verbatim}
-psTypeArray *psTypeNew(int n, int size);
+psTypeArray *psTypeAlloc(int n, int size);
 psTypeArray *psTypeRealloc(psTypeArray *arr, int n);
-void psTypeDel(psTypeArray *arr);  
+void psTypeFree(psTypeArray *arr);  
 \end{verbatim}
 
@@ -760 +774 @@
 and declares the prototypes (and is thus suitable for use in a
 header file); the latter generates the code for the three functions
-\code{psType(New|Realloc|Del} (and should thus appear in exactly one
+\code{psType(Alloc|Realloc|Free} (and should thus appear in exactly one
 source file for a given type).
 
@@ -772 +786 @@
 contains an array of \code{psType}s not
 pointers to \code{psType}s; this means that the individual elements are
-not allocated using \code{psTypeNew}, are not correctly initialized,
-and shouldn't be individually deleted with \code{psTypeDel};
+not allocated using \code{psTypeAlloc}, are not correctly initialized,
+and shouldn't be individually deleted with \code{psTypeFree};
 
 If you wish to use arrays of pointers, use the macros
@@ -788 +802 @@
 with associated constructors and a destructor:
 \begin{verbatim}
-psTypePtrArray *psTypePtrNew(int n, int size);
+psTypePtrArray *psTypePtrAlloc(int n, int size);
 psTypePtrArray *psTypePtrRealloc(psTypePtrArray *arr, int n);
-void psTypePtrArrayDel(psTypePtrArray *arr);  
+void psTypePtrArrayFree(psTypePtrArray *arr);  
 \end{verbatim}
 
 These constructors create arrays of \code{psType *} and call
-\code{psTypeNew} and \code{psTypeDel} to allocate and free the
+\code{psTypeAlloc} and \code{psTypeFree} to allocate and free the
 elements. As for the simple arrays, The former defines the typedef and
 declares the prototypes (and is thus suitable for use in a header
 file) and the latter generates the code for the three functions
-\code{psType(New|Realloc|Del} (and should thus appear in exactly one
+\code{psType(Alloc|Realloc|Free} (and should thus appear in exactly one
 source file for a given type).
 
@@ -805 +819 @@
 need to say something like:
 \begin{verbatim}
-  psTypePtrArray *pt = psTypePtrArrayNew(10, 10);
+  psTypePtrArray *pt = psTypePtrArrayAlloc(10, 10);
   psType *xy = psMemDecrRefCounter(pt->arr[0]);
   pt->arr[0] = NULL;
 \end{verbatim}
 
-\subsubsection{Arrays of \texttt{void *}}
+\subsubsection{Arrays of \code{void *}}
 \hlabel{secArrayVoidPtr}
 
@@ -825 +839 @@
 except that its destructor is specified as:
 \begin{verbatim}
-void psVoidPtrArrayDel(psVoidPtrArray *arr,      // array to destroy
-                       void (*elemDel)(void *)); // destructor for array data
-\end{verbatim}
-
-The routine \code{psVoidPtrArrayDel} assumes that all pointers
+void psVoidPtrArrayFree(psVoidPtrArray *arr,      // array to destroy
+                       void (*elemFree)(void *)); // destructor for array data
+\end{verbatim}
+
+The routine \code{psVoidPtrArrayFree} assumes that all pointers
 had their reference counters incremented
 when they were inserted onto the array.\footnote{%
   \eg{} \code{va->arr[i] = psMemIncrRefCounter(ptr);}}
 
-If \code{psVoidPtrArrayDel}'s argument \code{elemDel} is NULL, the
+If \code{psVoidPtrArrayFree}'s argument \code{elemFree} is NULL, the
 list should be deleted, but not the elements on it (although their
 \code{refcounter}'s should be decremented).
@@ -849 +863 @@
 } psXY;
 
-psXY *psXYNew(void)
+psXY *psXYAlloc(void)
 {
     return psAlloc(sizeof(psXY));
 }
 
-void psXYDel(psXY *xy)
+void psXYFree(psXY *xy)
 {
     psFree(xy);
@@ -867 +881 @@
 int main(void)
 {
-    psXYArray *t = psXYArrayNew(10, 15);
-    psXYPtrArray *pt = psXYPtrArrayNew(10, 10);
+    psXYArray *t = psXYArrayAlloc(10, 15);
+    psXYPtrArray *pt = psXYPtrArrayAlloc(10, 10);
 
     for (int i = 0; i < t->n; i++) {
@@ -883 +897 @@
     printf("\n");
     
-    psXYArrayDel(t);
+    psXYArrayFree(t);
 
     psXY *xy = psMemDecrRefCounter(pt->arr[0]);
     pt->arr[0] = NULL;
-    psXYDel(xy);    
+    psXYFree(xy);    
     
-    psXYPtrArrayDel(pt);
+    psXYPtrArrayFree(pt);
 
     psMemCheckLeaks(0, NULL, stderr);
@@ -904 +918 @@
 typedef struct HashTable psHash;
 
-psHash *psHashNew(int nbucket);         // initial number of buckets
-void psHashDel(psHash *table,           // hash table to be freed
-               void (*itemDel)(void *item)); // how to free hashed data;
-                                        // or NULL
-
-void *psHashInsert(psHash *table,       // table to insert in
-                   const char *key,     // key to use
-                   void *data,          // data to insert
-                   void (*itemDel)(void *item)); // how to free hashed data;
-                                        // or NULL
-void *psHashLookup(psHash *table,       // table to lookup key in
-                   const char *key);    // key to lookup
+psHash *psHashAlloc(int nbucket);       // initial number of buckets
+void psHashFree(psHash *table,          // hash table to be freed
+               void (*itemFree)(void *item)); // how to free hashed data;
+                                        // or NULL
+
+void *psHashInsert(psHash *table,       // table to insert in
+                   const char *key,     // key to use
+                   void *data,          // data to insert
+                   void (*itemFree)(void *item)); // how to free hashed data;
+                                        // or NULL
+void *psHashLookup(psHash *table,       // table to lookup key in
+                   const char *key);    // key to lookup
+
+void *psHashRemove(psHash *table,       // table to lookup key in
+                   const char *key);    // key to lookup
   \end{verbatim}
   \begin{caption}{The public API for hash tables from \file{psHash.h}}
@@ -926 +943 @@
 is included by \file{psUtils.h}.
 \footnote{
-  We choose not to use the posix function \texttt{hcreate},
-  \texttt{hdestroy}, and \code{hsearch} as they only support
+  We choose not to use the posix function \code{hcreate},
+  \code{hdestroy}, and \code{hsearch} as they only support
   a single hash table at any one time.}
 
-A hash table is an abstract type \texttt{psHash}.  The argument
-\texttt{nbucket} to \texttt{psHashNew} is a non-binding suggestion
+A hash table is an abstract type \code{psHash}.  The argument
+\code{nbucket} to \code{psHashAlloc} is a non-binding suggestion
 from the user for the initial size of the hash table.
 
-If the \texttt{itemDel} argument to \texttt{psHashDel} is non-NULL,
+If the \code{itemFree} argument to \code{psHashFree} is non-NULL,
 it will be used to delete the data items that have been stored
 in the hash table; if it is NULL this is the responsibility of
 the caller.
 
-The routine \texttt{psHashInsert} must provide a non-NULL \texttt{itemDel}
+The routine \code{psHashInsert} must provide a non-NULL \code{itemFree}
 argument if it wishes to change the value previously inserted keys;
-if \texttt{itemDel} is NULL attempting to insert a pre-existing key
-is an error, and the routine will return NULL.  If  \texttt{psHashInsert}
-succeeds it returns \texttt{data}.
-
-\texttt{psHashLookup} returns the \texttt{data} associated with the
+if \code{itemFree} is NULL attempting to insert a pre-existing key
+is an error, and the routine will return NULL.  If  \code{psHashInsert}
+succeeds it returns \code{data}.
+
+\code{psHashLookup} returns the \code{data} associated with the
 key, or NULL if the key's invalid.
+
+\code{psHashRemove} removes the entry associated with the
+key from the table, and returns the \code{data}; if the key's invalid it returns NULL.
 
 \section{Miscellaneous Utilities}