IPP Software Navigation Tools IPP Links Communication Pan-STARRS Links

Changeset 196


Ignore:
Timestamp:
Mar 9, 2004, 5:19:15 PM (22 years ago)
Author:
Paul Price
Message:

Doxygenation of Lupton stuff partially complete. Still need to hack some more to conform everything to coding standards.

Location:
trunk/archive/pslib/include
Files:
7 edited

Legend:

Unmodified
Added
Removed

  • trunk/archive/pslib/include/psArray.h

    r181 r196  
    33
    44#include <stdlib.h>
    5 /*
     5/**
    66 * Declare TYPEArray
    77 */
    … …  
    1919
    2020/*****************************************************************************/
    21 /*
     21/**
    2222 * Generate the code TYPEArray's constructors/destructors
    2323 */
    … …  
    7878
    7979/*****************************************************************************/
    80 /*
    81  * Support for pointer types
     80/**
     81 * Declare array of pointers
    8282 */
    8383#define PS_DECLARE_ARRAY_PTR_TYPE(TYPE) \
    … …  
    8585    PS_DECLARE_ARRAY_TYPE(PS_CONCAT(TYPE, Ptr))
    8686
     87/**
     88 * Create constructors/destructors for array of pointers
     89 */
    8790#define PS_CREATE_ARRAY_PTR_TYPE(TYPE); \
    8891    P_PS_CREATE_ARRAY_TYPE(static, my_, P_PS_CONCAT(TYPE, Ptr)) \
    … …  
    117120
    118121/*****************************************************************************/
    119 /*
    120  * Declare some common types of arrays
     122/**
     123 * Array of pointers to void.
    121124 *
    122125 * psVoidPtrArray is special, as it needs to have a destructor that
    … …  
    125128 */
    126129typedef struct {
    127    int n, size;
    128    void **arr;
     130    int n;                              //!< Number of elements in use
     131    int size;                           //!< Number of total elements
     132    void **arr;                         //!< The elements
    129133} psVoidPtrArray;
    130134
    131 psVoidPtrArray *psVoidPtrArrayAlloc(int n, int s);
    132 psVoidPtrArray *psVoidPtrArrayRealloc(psVoidPtrArray *arr, int n);
    133 void psVoidPtrArrayFree(psVoidPtrArray *arr,
    134                         void (*elemFree)(void *)); // destructor for array data
     135/** Constructor */
     136psVoidPtrArray *psVoidPtrArrayAlloc(int n, //!< Number of elements to use
     137                                    int s //!< Total number of elements
     138                                    );
     139/** Reallocate */
     140psVoidPtrArray *psVoidPtrArrayRealloc(psVoidPtrArray *arr, //!< Array to reallocate
     141                                      int n //!< Number of elements
     142                                      );
     143/** Destructor */
     144void psVoidPtrArrayFree(psVoidPtrArray *arr, //!< array to destroy
     145                        void (*elemFree)(void *) //!< destructor for array data
     146                        );
    135147
    136148

  • trunk/archive/pslib/include/psDlist.h

    r181 r196  
    44 * Support for doubly linked lists
    55 */
     6
     7/** Doubly-linked list element */
    68typedef struct psDlistElem {
    7    struct psDlistElem *prev;            // previous link in list
    8    struct psDlistElem *next;            // next link in list
    9    void *data;                          // real data item
     9   struct psDlistElem *prev;            //!< previous link in list
     10   struct psDlistElem *next;            //!< next link in list
     11   void *data;                          //!< real data item
    1012} psDlistElem;
    1113
     14/** Doubly-linked list */
    1215typedef struct {
    13    int n;                               // number of elements on list
    14    psDlistElem *head;                   // first element on list (may be NULL)
    15    psDlistElem *tail;                   // last element on list (may be NULL)
    16    psDlistElem *iter;                   // iteration cursor
     16   int n;                               //!< number of elements on list
     17   psDlistElem *head;                   //!< first element on list (may be NULL)
     18   psDlistElem *tail;                   //!< last element on list (may be NULL)
     19   psDlistElem *iter;                   //!< iteration cursor
    1720} psDlist;
    1821
    19 enum {                                  // Special values of index into list
    20    PS_DLIST_HEAD = 0,                   // at head
    21    PS_DLIST_TAIL = -1,                  // at tail
    22    PS_DLIST_UNKNOWN = -2,               // unknown position
    23    PS_DLIST_PREV = -3,                  // previous element
    24    PS_DLIST_NEXT = -4                   // next element
     22/** Special values of index into list */
     23enum {
     24   PS_DLIST_HEAD = 0,                   //!< at head
     25   PS_DLIST_TAIL = -1,                  //!< at tail
     26   PS_DLIST_UNKNOWN = -2,               //!< unknown position
     27   PS_DLIST_PREV = -3,                  //!< previous element
     28   PS_DLIST_NEXT = -4                   //!< next element
    2529};
    2630
    2731/*****************************************************************************/
    28 /*
    29  * Constructors and Destructors
    30  */
    31 psDlist *psDlistAlloc(void *data);      // initial data item; may be NULL
     32/** Constructor */
     33psDlist *psDlistAlloc(void *data        //!< initial data item; may be NULL
     34    );
    3235
    33 void psDlistFree(psDlist *list,         // list to destroy
    34                 void (*elemFree)(void *)); // destructor for data on list
     36/** Destructor */
     37void psDlistFree(psDlist *list,         //!< list to destroy
     38                void (*elemFree)(void *) //!< destructor for data on list
     39    );
    3540
    3641/*
    3742 * List maintainence functions
    3843 */
    39 psDlist *psDlistAdd(psDlist *list,      // list to add to (may be NULL)
    40                     void *data,         // data item to add
    41                     int where);         // index, PS_DLIST_HEAD, or PS_DLIST_TAIL
    42 psDlist *psDlistAppend(psDlist *list,   // list to append to (may be NULL)
    43                        void *data);     // data item to add
    44 void *psDlistRemove(psDlist *list,      // list to remove element from
    45                     void *data,         // data item to remove
    46                     int which);         // index of item, or PS_DLIST_UNKNOWN,
    47                                         // or PS_DLIST_NEXT, or PS_DLIST_PREV
    48 void *psDlistGet(const psDlist *list,   // list to retrieve element from
    49                  int which);            // index of item, or PS_DLIST_NEXT,
    50                                         // or PS_DLIST_PREV
     44
     45/** Add to list */
     46psDlist *psDlistAdd(psDlist *list,      //!< list to add to (may be NULL)
     47                    void *data,         //!< data item to add
     48                    int where           //!< index, PS_DLIST_HEAD, or PS_DLIST_TAIL
     49    );
     50
     51/** Append to a list */
     52psDlist *psDlistAppend(psDlist *list,   //!< list to append to (may be NULL)
     53                       void *data       //!< data item to add
     54    );
     55
     56/** Remove from a list */
     57void *psDlistRemove(psDlist *list,      //!< list to remove element from
     58                    void *data,         //!< data item to remove
     59                    int which           //!< index of item, or PS_DLIST_UNKNOWN, or PS_DLIST_NEXT, or
     60                                        //!< PS_DLIST_PREV
     61    );
     62
     63/** Retrieve from a list */
     64void *psDlistGet(const psDlist *list,   //!< list to retrieve element from
     65                 int which              //!< index of item, or PS_DLIST_NEXT, or PS_DLIST_PREV
     66    );
     67
    5168/*
    5269 * convenience functions to use psDlistGet as an iterator
    5370 */
    54 void psDlistSetIterator(psDlist *list, int where, int which);
    55 void *psDlistGetNext(psDlist *list, int which);
    56 void *psDlistGetPrev(psDlist *list, int which);
    57 /*
    58  * Conversions to/from arrays
    59  */
    60 psVoidPtrArray *psDlistToArray(psDlist *dlist);
    61 psDlist *psArrayToDlist(psVoidPtrArray *arr);
     71
     72/** Set the iterator */
     73void psDlistSetIterator(psDlist *list,  //!< list to retrieve element from
     74                        int where,      //!< index, PS_DLIST_HEAD, or PS_DLIST_TAIL
     75                        int which       //!< index of item, or PS_DLIST_UNKNOWN, or PS_DLIST_NEXT, or
     76                                        //!< PS_DLIST_PREV
     77    );
     78
     79/** Get next element */
     80void *psDlistGetNext(psDlist *list,     //!< list to retrieve element from
     81                     int which          //!< index of item, or PS_DLIST_UNKNOWN, or PS_DLIST_NEXT, or
     82                                        //!< PS_DLIST_PREV
     83    );
     84
     85/** Get previous element */
     86void *psDlistGetPrev(psDlist *list,     //!< list to retrieve element from
     87                     int which          //!< index of item, or PS_DLIST_UNKNOWN, or PS_DLIST_NEXT, or
     88                                        //!< PS_DLIST_PREV
     89    );
     90
     91
     92/** Convert doubly-linked list to an array */
     93psVoidPtrArray *psDlistToArray(psDlist *dlist //!< List to convert
     94    );
     95
     96/** Convert array to a doubly-linked list */
     97psDlist *psArrayToDlist(psVoidPtrArray *arr //!< Array to convert
     98    );
     99
     100
    62101#endif

  • trunk/archive/pslib/include/psHash.h

    r181 r196  
    22#define PS_HASH_H
    33
    4 typedef struct HashTable psHash;
     4typedef struct HashTable psHash;        //!< Opaque type for a hash table
    55
    6 psHash *psHashAlloc(int nbucket);       // initial number of buckets
    7 void psHashFree(psHash *table,          // hash table to be freed
    8                 void (*itemFree)(void *item)); // how to free hashed data;
    9                                         // or NULL
     6psHash *psHashAlloc(int nbucket         //!< initial number of buckets
     7    );
     8void psHashFree(psHash *table,          //!< hash table to be freed
     9                void (*itemFree)(void *item) //!< how to free hashed data; or NULL
     10    );
    1011
    11 void *psHashInsert(psHash *table,       // table to insert in
    12                    const char *key,     // key to use
    13                    void *data,          // data to insert
    14                    void (*itemFree)(void *item)); // how to free hashed data;
    15                                         // or NULL
    16 void *psHashLookup(psHash *table,       // table to lookup key in
    17                    const char *key);    // key to lookup
     12void *psHashInsert(psHash *table,       //!< table to insert in
     13                   const char *key,     //!< key to use
     14                   void *data,          //!< data to insert
     15                   void (*itemFree)(void *item) //!< how to free hashed data; or NULL
     16    );
     17void *psHashLookup(psHash *table,       //!< table to lookup key in
     18                   const char *key      //!< key to lookup
     19    );
    1820
    19 void *psHashRemove(psHash *table,       // table to lookup key in
    20                    const char *key);    // key to lookup
     21void *psHashRemove(psHash *table,       //!< table to lookup key in
     22                   const char *key      //!< key to lookup
     23    );
     24
     25
    2126#endif

  • trunk/archive/pslib/include/psLogMsg.h

    r181 r196  
    33#include <stdarg.h>
    44
    5 enum { PS_LOG_ABORT = 0, PS_LOG_ERROR, PS_LOG_WARN, PS_LOG_INFO };
     5enum { PS_LOG_ABORT = 0, PS_LOG_ERROR, PS_LOG_WARN, PS_LOG_INFO }; //!< Status codes for log messages
    66
    7 enum { PS_LOG_TO_STDERR, PS_LOG_TO_STDOUT };
     7enum { PS_LOG_TO_STDERR, PS_LOG_TO_STDOUT }; //!< Destinations for log messages
    88
    9 int psSetLogDestination(int dest);
    10 int psSetLogLevel(int level);
    11 void psSetLogFormat(const char *fmt);
     9int psSetLogDestination(int dest);      //!< Sets the log destination
     10int psSetLogLevel(int level);           //!< Sets the log level
     11void psSetLogFormat(const char *fmt);   //!< sets the log format
    1212
    13 void psLogMsg(const char *name, int level, const char *fmt, ...);
    14 void p_psVLogMsg(const char *name, int level, const char *fmt, va_list ap);
     13void psLogMsg(const char *name, int level, const char *fmt, ...); //!< Logs a message
     14void p_psVLogMsg(const char *name, int level, const char *fmt, va_list ap); //!< Logs a message from varargs
    1515
    1616#endif

  • trunk/archive/pslib/include/psMemory.h

    r181 r196  
    22#define PS_MEMORY_H
    33#include <stdio.h>
    4 /*
    5  * Book-keeping data for storage allocator
     4/**
     5 * Book-keeping data for storage allocator.
    66 *
    77 * N.b. sizeof(psMemBlock) must be chosen such that if ptr is a pointer
    … …  
    1010 */
    1111typedef struct {
    12     const void *magic0;                 // initialised to p_psMEMMAGIC
    13     const unsigned long id;             // a unique ID for this allocation
    14     const char *file;                   // set from __FILE__ in e.g. p_psAlloc
    15     const int lineno;                   // set from __LINE__ in e.g. p_psAlloc
    16     int refCounter;                     // how many times pointer is referenced
    17     const void *magic;                  // initialised to p_psMEMMAGIC
     12    const void *magic0;                 //!< initialised to p_psMEMMAGIC
     13    const unsigned long id;             //!< a unique ID for this allocation
     14    const char *file;                   //!< set from __FILE__ in e.g. p_psAlloc
     15    const int lineno;                   //!< set from __LINE__ in e.g. p_psAlloc
     16    int refCounter;                     //!< how many times pointer is referenced
     17    const void *magic;                  //!< initialised to p_psMEMMAGIC
    1818} psMemBlock;
    1919
     20/** */
    2021typedef int (*psMemCallback)(const psMemBlock *ptr);
    2122typedef void (*psMemProblemCallback)(const psMemBlock *ptr,
    … …  
    2526/*****************************************************************************/
    2627
    27 void *psAlloc(size_t size);
    28 void *psRealloc(void *ptr, size_t size);
    29 void psFree(void *ptr);
     28/** Fake for p_psAlloc */
     29void *psAlloc(size_t size               //!< Size required
     30    );
     31/** Fake for p_psRealloc */
     32void *psRealloc(void *ptr,              //!< Pointer to re-allocate
     33                size_t size             //!< Size required
     34    );
     35/** Fake for p_psFree */
     36void psFree(void *ptr                   //!< Pointer to free
     37    );
    3038
    31 void *p_psAlloc(size_t size, const char *file, int lineno);
    32 void *p_psRealloc(void *ptr, size_t size, const char *file, int lineno);
    33 void p_psFree(void *ptr, const char *file, int lineno);
     39/** Memory allocation */
     40void *p_psAlloc(size_t size,            //!< Size required
     41                const char *file,       //!< File of call
     42                int lineno              //!< Line number of call
     43    );
    3444
     45/** Memory re-allocation */
     46void *p_psRealloc(void *ptr,            //!< Pointer to re-allocate
     47                  size_t size,          //!< Size required
     48                  const char *file,     //!< File of call
     49                  int lineno            //!< Line number of call
     50    );
     51
     52/** Free memory */
     53void p_psFree(void *ptr,                //!< Pointer to free
     54              const char *file,         //!< File of call
     55              int lineno                //!< Line number of call
     56    );
     57
     58/** psAlloc sends file and line number to p_psAlloc */
    3559#define psAlloc(size) p_psAlloc(size, __FILE__, __LINE__)
     60/** psRealloc sends file and line number to p_psRealloc */
    3661#define psRealloc(ptr, size) p_psRealloc(ptr, size, __FILE__, __LINE__)
     62/** psFree sends file and line number to p_psFree */
    3763#define psFree(size) p_psFree(size, __FILE__, __LINE__)
    3864
    3965/*****************************************************************************/
    40 /*
    41  * Checks of memory system
    42  */
    43 int psMemCheckLeaks(
    44     int id0,                            // don't list blocks with id < id0
    45     psMemBlock ***arr,                  // pointer to array of pointers to
    46                                         // leaked blocks, or NULL
    47     FILE *fd);                          // print list of leaks to fd (or NULL)
    48 int psMemCheckCorruption(int abort_on_error);
     66/** Check for memory leaks */
     67int psMemCheckLeaks(int id0,            //!< don't list blocks with id < id0
     68                    psMemBlock ***arr,  //!< pointer to array of pointers to leaked blocks, or NULL
     69                    FILE *fd            //!< print list of leaks to fd (or NULL)
     70    );
     71
     72/** Check for memory corruption */
     73int psMemCheckCorruption(int abort_on_error //!< Abort on detecting corruption?
     74    );
    4975
    5076/*****************************************************************************/
    51 /*
    52  * Manipulate reference counter
    53  */
    54 int psMemGetRefCounter(void *vptr);     // return refCounter
    55 void *psMemIncrRefCounter(void *vptr);  // increment refCounter and return vptr
    56 void *psMemDecrRefCounter(void *vptr);  // decrement refCounter and return vptr
     77
     78/** Return reference counter */
     79int psMemGetRefCounter(void *vptr       //!< Pointer to get refCounter for
     80    );
     81/** Increment reference counter and return the pointer */
     82void *psMemIncrRefCounter(void *vptr    //!< Pointer to increment refCounter, and return
     83    );
     84/** Decrement reference counter and return the pointer */
     85void *psMemDecrRefCounter(void *vptr    //!< Pointer to decrement refCounter, and return
     86    );
    5787
    5888/*****************************************************************************/
    … …  
    6090 * Functions to set and control callbacks
    6191 */
    62 psMemProblemCallback psMemProblemSetCB(psMemProblemCallback func);
    63 psMemExhaustedCallback psMemExhaustedSetCB(psMemExhaustedCallback func);
    6492
    65 psMemCallback psMemAllocateSetCB(psMemCallback func);
    66 psMemCallback psMemFreeSetCB(psMemCallback func);
     93/** Set callback for problems */
     94psMemProblemCallback psMemProblemSetCB(psMemProblemCallback func //!< Function to run
     95    );
     96psMemExhaustedCallback psMemExhaustedSetCB(psMemExhaustedCallback func); //!< set call back for exhausted
     97                                                                         //!< memory
    6798
    68 int psMemGetId(void);                   // get next memory ID
    69 long psMemSetAllocateID(long id);       // set p_psMemAllocateID to id
    70 long psMemSetFreeID(long id);           // set p_psMemFreeID to id
     99psMemCallback psMemAllocateSetCB(psMemCallback func); //!< Set call back for when a particular memory block is
     100                                                      //!< allocated
     101psMemCallback psMemFreeSetCB(psMemCallback func); //!< set call back for when a particular memory block is
     102                                                  //!< freed
     103
     104int psMemGetId(void);                   //!< get next memory ID
     105long psMemSetAllocateID(long id);       //!< set p_psMemAllocateID to id
     106long psMemSetFreeID(long id);           //!< set p_psMemFreeID to id
    71107#endif

  • trunk/archive/pslib/include/psMisc.h

    r181 r196  
    11#if !defined(PS_MISC_H)
    22#define PS_MISC_H
    3 /*
     3/**
    44 * Concatenate two macro arguments
    55 */
    6 #define P_PS_CONCAT(A, B) A ## B        // Expands to AB
    7 #define PS_CONCAT(A, B) A ## B          // Also Expands to AB
    8 #define PS_CONCAT2(A, B) PS_CONCAT(A, B) // Also expands to AB
    9 #define PS_CONCAT3(A, B, C) A ## B ## C // Expands to ABC
    10 #define PS_CONCAT4(A, B, C, D) A ## B ## C ## D // Expands to ABCD
     6#define P_PS_CONCAT(A, B) A ## B        //!< Expands to AB
     7#define PS_CONCAT(A, B) A ## B          //!< Also Expands to AB
     8#define PS_CONCAT2(A, B) PS_CONCAT(A, B) //!< Also expands to AB
     9#define PS_CONCAT3(A, B, C) A ## B ## C //!< Expands to ABC
     10#define PS_CONCAT4(A, B, C, D) A ## B ## C ## D //!< Expands to ABCD
    1111
    12 #define PS_STRING(S) #S                 // converts argument to string
     12#define PS_STRING(S) #S                 //!< converts argument to string
    1313
    14 void psAbort(const char *name, const char *fmt, ...);
    15 void psError(const char *name, const char *fmt, ...);
     14/** Prints an error message and aborts */
     15void psAbort(const char *name,          //!< Category of code that caused the abort
     16             const char *fmt,           //!< Format
     17             ...                        //!< Extra arguments to use format
     18    );
     19/** Prints an error message and doesn't abort */
     20void psError(const char *name,          //!< Category of code that caused the abort
     21             const char *fmt,           //!< Format
     22             ...                        //!< Extra arguments to use format
     23    );
    1624
    17 char *psStringCopy(const char *str);
     25/** Allocates and returns a copy of a string */
     26char *psStringCopy(const char *str      //!< string to copy
     27    );
    1828
    1929#endif

  • trunk/archive/pslib/include/psTrace.h

    r181 r196  
    22#define PS_TRACE_H 1
    33
    4 //#define PS_NTRACE 1                   /* to turn off all tracing */
     4//#define PS_NTRACE 1                   //!< to turn off all tracing
    55#if defined(PS_NTRACE)
    6 #  define psTrace(facil, level, ...) /* do nothing */
     6#  define psTrace(facil, level, ...)    /* do nothing */
    77#else
    88#  define psTrace(facil, level, ...) \
    … …  
    1010#endif
    1111
     12/** Send a trace message */
    1213void p_psTrace(const char *facil, int level, ...);
    1314
    14 int psSetTraceLevel(const char *facil,  // facilty of interest
    15                     int level);         // desired trace level
    16 int psGetTraceLevel(const char *name);  // facilty of interest
     15/** Set trace level */
     16int psSetTraceLevel(const char *facil,  //!< facilty of interest
     17                    int level           //!< desired trace level
     18    );
    1719
    18 void psTraceReset(void);                // turn off all tracing, and free trace's allocated memory
     20/** Get the trace level */
     21int psGetTraceLevel(const char *name    //!< facilty of interest
     22    );
    1923
    20 void psPrintTraceLevels(void);          // print trace levels
     24/** turn off all tracing, and free trace's allocated memory */
     25void psTraceReset(void);
     26
     27/** print trace levels */
     28void psPrintTraceLevels(void);
    2129
    2230#endif
Note: See TracChangeset for help on using the changeset viewer.