Index: /trunk/archive/pslib/include/psArray.h =================================================================== --- /trunk/archive/pslib/include/psArray.h (revision 195) +++ /trunk/archive/pslib/include/psArray.h (revision 196) @@ -3,5 +3,5 @@ #include -/* +/** * Declare TYPEArray */ @@ -19,5 +19,5 @@ /*****************************************************************************/ -/* +/** * Generate the code TYPEArray's constructors/destructors */ @@ -78,6 +78,6 @@ /*****************************************************************************/ -/* - * Support for pointer types +/** + * Declare array of pointers */ #define PS_DECLARE_ARRAY_PTR_TYPE(TYPE) \ @@ -85,4 +85,7 @@ PS_DECLARE_ARRAY_TYPE(PS_CONCAT(TYPE, Ptr)) +/** + * Create constructors/destructors for array of pointers + */ #define PS_CREATE_ARRAY_PTR_TYPE(TYPE); \ P_PS_CREATE_ARRAY_TYPE(static, my_, P_PS_CONCAT(TYPE, Ptr)) \ @@ -117,6 +120,6 @@ /*****************************************************************************/ -/* - * Declare some common types of arrays +/** + * Array of pointers to void. * * psVoidPtrArray is special, as it needs to have a destructor that @@ -125,12 +128,21 @@ */ typedef struct { - int n, size; - void **arr; + int n; //!< Number of elements in use + int size; //!< Number of total elements + void **arr; //!< The elements } psVoidPtrArray; -psVoidPtrArray *psVoidPtrArrayAlloc(int n, int s); -psVoidPtrArray *psVoidPtrArrayRealloc(psVoidPtrArray *arr, int n); -void psVoidPtrArrayFree(psVoidPtrArray *arr, - void (*elemFree)(void *)); // destructor for array data +/** Constructor */ +psVoidPtrArray *psVoidPtrArrayAlloc(int n, //!< Number of elements to use + int s //!< Total number of elements + ); +/** Reallocate */ +psVoidPtrArray *psVoidPtrArrayRealloc(psVoidPtrArray *arr, //!< Array to reallocate + int n //!< Number of elements + ); +/** Destructor */ +void psVoidPtrArrayFree(psVoidPtrArray *arr, //!< array to destroy + void (*elemFree)(void *) //!< destructor for array data + ); Index: /trunk/archive/pslib/include/psDlist.h =================================================================== --- /trunk/archive/pslib/include/psDlist.h (revision 195) +++ /trunk/archive/pslib/include/psDlist.h (revision 196) @@ -4,59 +4,98 @@ * Support for doubly linked lists */ + +/** Doubly-linked list element */ typedef struct psDlistElem { - struct psDlistElem *prev; // previous link in list - struct psDlistElem *next; // next link in list - void *data; // real data item + struct psDlistElem *prev; //!< previous link in list + struct psDlistElem *next; //!< next link in list + void *data; //!< real data item } psDlistElem; +/** Doubly-linked list */ typedef struct { - int n; // number of elements on list - psDlistElem *head; // first element on list (may be NULL) - psDlistElem *tail; // last element on list (may be NULL) - psDlistElem *iter; // iteration cursor + int n; //!< number of elements on list + psDlistElem *head; //!< first element on list (may be NULL) + psDlistElem *tail; //!< last element on list (may be NULL) + psDlistElem *iter; //!< iteration cursor } psDlist; -enum { // Special values of index into list - PS_DLIST_HEAD = 0, // at head - PS_DLIST_TAIL = -1, // at tail - PS_DLIST_UNKNOWN = -2, // unknown position - PS_DLIST_PREV = -3, // previous element - PS_DLIST_NEXT = -4 // next element +/** Special values of index into list */ +enum { + PS_DLIST_HEAD = 0, //!< at head + PS_DLIST_TAIL = -1, //!< at tail + PS_DLIST_UNKNOWN = -2, //!< unknown position + PS_DLIST_PREV = -3, //!< previous element + PS_DLIST_NEXT = -4 //!< next element }; /*****************************************************************************/ -/* - * Constructors and Destructors - */ -psDlist *psDlistAlloc(void *data); // initial data item; may be NULL +/** Constructor */ +psDlist *psDlistAlloc(void *data //!< initial data item; may be NULL + ); -void psDlistFree(psDlist *list, // list to destroy - void (*elemFree)(void *)); // destructor for data on list +/** Destructor */ +void psDlistFree(psDlist *list, //!< list to destroy + void (*elemFree)(void *) //!< destructor for data on list + ); /* * List maintainence functions */ -psDlist *psDlistAdd(psDlist *list, // list to add to (may be NULL) - void *data, // data item to add - int where); // index, PS_DLIST_HEAD, or PS_DLIST_TAIL -psDlist *psDlistAppend(psDlist *list, // list to append to (may be NULL) - void *data); // data item to add -void *psDlistRemove(psDlist *list, // list to remove element from - void *data, // data item to remove - int which); // index of item, or PS_DLIST_UNKNOWN, - // or PS_DLIST_NEXT, or PS_DLIST_PREV -void *psDlistGet(const psDlist *list, // list to retrieve element from - int which); // index of item, or PS_DLIST_NEXT, - // or PS_DLIST_PREV + +/** Add to list */ +psDlist *psDlistAdd(psDlist *list, //!< list to add to (may be NULL) + void *data, //!< data item to add + int where //!< index, PS_DLIST_HEAD, or PS_DLIST_TAIL + ); + +/** Append to a list */ +psDlist *psDlistAppend(psDlist *list, //!< list to append to (may be NULL) + void *data //!< data item to add + ); + +/** Remove from a list */ +void *psDlistRemove(psDlist *list, //!< list to remove element from + void *data, //!< data item to remove + int which //!< index of item, or PS_DLIST_UNKNOWN, or PS_DLIST_NEXT, or + //!< PS_DLIST_PREV + ); + +/** Retrieve from a list */ +void *psDlistGet(const psDlist *list, //!< list to retrieve element from + int which //!< index of item, or PS_DLIST_NEXT, or PS_DLIST_PREV + ); + /* * convenience functions to use psDlistGet as an iterator */ -void psDlistSetIterator(psDlist *list, int where, int which); -void *psDlistGetNext(psDlist *list, int which); -void *psDlistGetPrev(psDlist *list, int which); -/* - * Conversions to/from arrays - */ -psVoidPtrArray *psDlistToArray(psDlist *dlist); -psDlist *psArrayToDlist(psVoidPtrArray *arr); + +/** Set the iterator */ +void psDlistSetIterator(psDlist *list, //!< list to retrieve element from + int where, //!< index, PS_DLIST_HEAD, or PS_DLIST_TAIL + int which //!< index of item, or PS_DLIST_UNKNOWN, or PS_DLIST_NEXT, or + //!< PS_DLIST_PREV + ); + +/** Get next element */ +void *psDlistGetNext(psDlist *list, //!< list to retrieve element from + int which //!< index of item, or PS_DLIST_UNKNOWN, or PS_DLIST_NEXT, or + //!< PS_DLIST_PREV + ); + +/** Get previous element */ +void *psDlistGetPrev(psDlist *list, //!< list to retrieve element from + int which //!< index of item, or PS_DLIST_UNKNOWN, or PS_DLIST_NEXT, or + //!< PS_DLIST_PREV + ); + + +/** Convert doubly-linked list to an array */ +psVoidPtrArray *psDlistToArray(psDlist *dlist //!< List to convert + ); + +/** Convert array to a doubly-linked list */ +psDlist *psArrayToDlist(psVoidPtrArray *arr //!< Array to convert + ); + + #endif Index: /trunk/archive/pslib/include/psHash.h =================================================================== --- /trunk/archive/pslib/include/psHash.h (revision 195) +++ /trunk/archive/pslib/include/psHash.h (revision 196) @@ -2,20 +2,25 @@ #define PS_HASH_H -typedef struct HashTable psHash; +typedef struct HashTable psHash; //!< Opaque type for a hash table -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 +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 *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 +void *psHashRemove(psHash *table, //!< table to lookup key in + const char *key //!< key to lookup + ); + + #endif Index: /trunk/archive/pslib/include/psLogMsg.h =================================================================== --- /trunk/archive/pslib/include/psLogMsg.h (revision 195) +++ /trunk/archive/pslib/include/psLogMsg.h (revision 196) @@ -3,14 +3,14 @@ #include -enum { PS_LOG_ABORT = 0, PS_LOG_ERROR, PS_LOG_WARN, PS_LOG_INFO }; +enum { PS_LOG_ABORT = 0, PS_LOG_ERROR, PS_LOG_WARN, PS_LOG_INFO }; //!< Status codes for log messages -enum { PS_LOG_TO_STDERR, PS_LOG_TO_STDOUT }; +enum { PS_LOG_TO_STDERR, PS_LOG_TO_STDOUT }; //!< Destinations for log messages -int psSetLogDestination(int dest); -int psSetLogLevel(int level); -void psSetLogFormat(const char *fmt); +int psSetLogDestination(int dest); //!< Sets the log destination +int psSetLogLevel(int level); //!< Sets the log level +void psSetLogFormat(const char *fmt); //!< sets the log format -void psLogMsg(const char *name, int level, const char *fmt, ...); -void p_psVLogMsg(const char *name, int level, const char *fmt, va_list ap); +void psLogMsg(const char *name, int level, const char *fmt, ...); //!< Logs a message +void p_psVLogMsg(const char *name, int level, const char *fmt, va_list ap); //!< Logs a message from varargs #endif Index: /trunk/archive/pslib/include/psMemory.h =================================================================== --- /trunk/archive/pslib/include/psMemory.h (revision 195) +++ /trunk/archive/pslib/include/psMemory.h (revision 196) @@ -2,6 +2,6 @@ #define PS_MEMORY_H #include -/* - * Book-keeping data for storage allocator +/** + * Book-keeping data for storage allocator. * * N.b. sizeof(psMemBlock) must be chosen such that if ptr is a pointer @@ -10,12 +10,13 @@ */ typedef struct { - const void *magic0; // initialised to p_psMEMMAGIC - const unsigned long id; // a unique ID for this allocation - const char *file; // set from __FILE__ in e.g. p_psAlloc - const int lineno; // set from __LINE__ in e.g. p_psAlloc - int refCounter; // how many times pointer is referenced - const void *magic; // initialised to p_psMEMMAGIC + const void *magic0; //!< initialised to p_psMEMMAGIC + const unsigned long id; //!< a unique ID for this allocation + const char *file; //!< set from __FILE__ in e.g. p_psAlloc + const int lineno; //!< set from __LINE__ in e.g. p_psAlloc + int refCounter; //!< how many times pointer is referenced + const void *magic; //!< initialised to p_psMEMMAGIC } psMemBlock; +/** */ typedef int (*psMemCallback)(const psMemBlock *ptr); typedef void (*psMemProblemCallback)(const psMemBlock *ptr, @@ -25,34 +26,63 @@ /*****************************************************************************/ -void *psAlloc(size_t size); -void *psRealloc(void *ptr, size_t size); -void psFree(void *ptr); +/** Fake for p_psAlloc */ +void *psAlloc(size_t size //!< Size required + ); +/** Fake for p_psRealloc */ +void *psRealloc(void *ptr, //!< Pointer to re-allocate + size_t size //!< Size required + ); +/** Fake for p_psFree */ +void psFree(void *ptr //!< Pointer to free + ); -void *p_psAlloc(size_t size, const char *file, int lineno); -void *p_psRealloc(void *ptr, size_t size, const char *file, int lineno); -void p_psFree(void *ptr, const char *file, int lineno); +/** Memory allocation */ +void *p_psAlloc(size_t size, //!< Size required + const char *file, //!< File of call + int lineno //!< Line number of call + ); +/** Memory re-allocation */ +void *p_psRealloc(void *ptr, //!< Pointer to re-allocate + size_t size, //!< Size required + const char *file, //!< File of call + int lineno //!< Line number of call + ); + +/** Free memory */ +void p_psFree(void *ptr, //!< Pointer to free + const char *file, //!< File of call + int lineno //!< Line number of call + ); + +/** psAlloc sends file and line number to p_psAlloc */ #define psAlloc(size) p_psAlloc(size, __FILE__, __LINE__) +/** psRealloc sends file and line number to p_psRealloc */ #define psRealloc(ptr, size) p_psRealloc(ptr, size, __FILE__, __LINE__) +/** psFree sends file and line number to p_psFree */ #define psFree(size) p_psFree(size, __FILE__, __LINE__) /*****************************************************************************/ -/* - * Checks of memory system - */ -int psMemCheckLeaks( - int id0, // don't list blocks with id < id0 - psMemBlock ***arr, // pointer to array of pointers to - // leaked blocks, or NULL - FILE *fd); // print list of leaks to fd (or NULL) -int psMemCheckCorruption(int abort_on_error); +/** Check for memory leaks */ +int psMemCheckLeaks(int id0, //!< don't list blocks with id < id0 + psMemBlock ***arr, //!< pointer to array of pointers to leaked blocks, or NULL + FILE *fd //!< print list of leaks to fd (or NULL) + ); + +/** Check for memory corruption */ +int psMemCheckCorruption(int abort_on_error //!< Abort on detecting corruption? + ); /*****************************************************************************/ -/* - * Manipulate reference counter - */ -int psMemGetRefCounter(void *vptr); // return refCounter -void *psMemIncrRefCounter(void *vptr); // increment refCounter and return vptr -void *psMemDecrRefCounter(void *vptr); // decrement refCounter and return vptr + +/** Return reference counter */ +int psMemGetRefCounter(void *vptr //!< Pointer to get refCounter for + ); +/** Increment reference counter and return the pointer */ +void *psMemIncrRefCounter(void *vptr //!< Pointer to increment refCounter, and return + ); +/** Decrement reference counter and return the pointer */ +void *psMemDecrRefCounter(void *vptr //!< Pointer to decrement refCounter, and return + ); /*****************************************************************************/ @@ -60,12 +90,18 @@ * Functions to set and control callbacks */ -psMemProblemCallback psMemProblemSetCB(psMemProblemCallback func); -psMemExhaustedCallback psMemExhaustedSetCB(psMemExhaustedCallback func); -psMemCallback psMemAllocateSetCB(psMemCallback func); -psMemCallback psMemFreeSetCB(psMemCallback func); +/** Set callback for problems */ +psMemProblemCallback psMemProblemSetCB(psMemProblemCallback func //!< Function to run + ); +psMemExhaustedCallback psMemExhaustedSetCB(psMemExhaustedCallback func); //!< set call back for exhausted + //!< memory -int psMemGetId(void); // get next memory ID -long psMemSetAllocateID(long id); // set p_psMemAllocateID to id -long psMemSetFreeID(long id); // set p_psMemFreeID to id +psMemCallback psMemAllocateSetCB(psMemCallback func); //!< Set call back for when a particular memory block is + //!< allocated +psMemCallback psMemFreeSetCB(psMemCallback func); //!< set call back for when a particular memory block is + //!< freed + +int psMemGetId(void); //!< get next memory ID +long psMemSetAllocateID(long id); //!< set p_psMemAllocateID to id +long psMemSetFreeID(long id); //!< set p_psMemFreeID to id #endif Index: /trunk/archive/pslib/include/psMisc.h =================================================================== --- /trunk/archive/pslib/include/psMisc.h (revision 195) +++ /trunk/archive/pslib/include/psMisc.h (revision 196) @@ -1,19 +1,29 @@ #if !defined(PS_MISC_H) #define PS_MISC_H -/* +/** * Concatenate two macro arguments */ -#define P_PS_CONCAT(A, B) A ## B // Expands to AB -#define PS_CONCAT(A, B) A ## B // Also Expands to AB -#define PS_CONCAT2(A, B) PS_CONCAT(A, B) // Also expands to AB -#define PS_CONCAT3(A, B, C) A ## B ## C // Expands to ABC -#define PS_CONCAT4(A, B, C, D) A ## B ## C ## D // Expands to ABCD +#define P_PS_CONCAT(A, B) A ## B //!< Expands to AB +#define PS_CONCAT(A, B) A ## B //!< Also Expands to AB +#define PS_CONCAT2(A, B) PS_CONCAT(A, B) //!< Also expands to AB +#define PS_CONCAT3(A, B, C) A ## B ## C //!< Expands to ABC +#define PS_CONCAT4(A, B, C, D) A ## B ## C ## D //!< Expands to ABCD -#define PS_STRING(S) #S // converts argument to string +#define PS_STRING(S) #S //!< converts argument to string -void psAbort(const char *name, const char *fmt, ...); -void psError(const char *name, const char *fmt, ...); +/** Prints an error message and aborts */ +void psAbort(const char *name, //!< Category of code that caused the abort + const char *fmt, //!< Format + ... //!< Extra arguments to use format + ); +/** Prints an error message and doesn't abort */ +void psError(const char *name, //!< Category of code that caused the abort + const char *fmt, //!< Format + ... //!< Extra arguments to use format + ); -char *psStringCopy(const char *str); +/** Allocates and returns a copy of a string */ +char *psStringCopy(const char *str //!< string to copy + ); #endif Index: /trunk/archive/pslib/include/psTrace.h =================================================================== --- /trunk/archive/pslib/include/psTrace.h (revision 195) +++ /trunk/archive/pslib/include/psTrace.h (revision 196) @@ -2,7 +2,7 @@ #define PS_TRACE_H 1 -//#define PS_NTRACE 1 /* to turn off all tracing */ +//#define PS_NTRACE 1 //!< to turn off all tracing #if defined(PS_NTRACE) -# define psTrace(facil, level, ...) /* do nothing */ +# define psTrace(facil, level, ...) /* do nothing */ #else # define psTrace(facil, level, ...) \ @@ -10,13 +10,21 @@ #endif +/** Send a trace message */ void p_psTrace(const char *facil, int level, ...); -int psSetTraceLevel(const char *facil, // facilty of interest - int level); // desired trace level -int psGetTraceLevel(const char *name); // facilty of interest +/** Set trace level */ +int psSetTraceLevel(const char *facil, //!< facilty of interest + int level //!< desired trace level + ); -void psTraceReset(void); // turn off all tracing, and free trace's allocated memory +/** Get the trace level */ +int psGetTraceLevel(const char *name //!< facilty of interest + ); -void psPrintTraceLevels(void); // print trace levels +/** turn off all tracing, and free trace's allocated memory */ +void psTraceReset(void); + +/** print trace levels */ +void psPrintTraceLevels(void); #endif