- doxygen-ized the important functions

- made the macros uppercase
- made the functions not have leading "_"'s

This commit was SVN r47.

src/lam/util/malloc.h

@@ -1,4 +1,6 @@
 /*
+ * $HEADER$
+ *
  * Copyright 2002-2003. The Regents of the University of California. This material
  * was produced under U.S. Government contract W-7405-ENG-36 for Los Alamos
  * National Laboratory, which is operated by the University of California for
@@ -28,8 +30,9 @@
  */
 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 
-#ifndef _LAM_MALLOC_H_
-#define _LAM_MALLOC_H_
+/** @file */                                                                                                     
+#ifndef LAM_MALLOC_H
+#define LAM_MALLOC_H
 
 #include <stdlib.h>
 #include "lam_config.h"
@@ -46,37 +49,61 @@
 #define LAM_MALLOC_DEBUG_LEVEL 2
 #endif
 
-/*
- * malloc and free with error checking
+/**
+ * Back-end error-checking malloc function for LAM (you should use the
+ * LAM_MALLOC() macro instead of this function).
+ *
+ * @param size The number of bytes to allocate
+ * @param debug_level What debug level to use (0=none, 1=some, 2=more)
+ * @param file Typically the __FILE__ macro
+ * @param line Typically the __LINE__ macro
  */
-
-static inline void *_lam_malloc(ssize_t size, int debug_level, char *file, int line)
+inline void *lam_malloc(size_t size, int debug_level, char *file, int line)
 {
     void *addr = NULL;
     if (debug_level > 1) {
         if (size <= 0) {
-            _lam_set_file_line(file, line);
-            _lam_warn("Warning: ulm_malloc: Request for %ld bytes\n",
+#if 0
+          /* JMS Replace with logging output */
+            lam_set_file_line(file, line);
+            lam_warn("Warning: lam_malloc: Request for %ld bytes\n",
                       (long) size);
+#endif
         }
     }
-    addr = malloc((size_t) size);
+    addr = malloc(size);
     if (debug_level > 0) {
         if (addr == NULL) {
-            _lam_set_file_line(file, line);
-            _lam_err("Error: ulm_malloc: Request for %ld bytes failed\n",
+#if 0
+          /* JMS Replace with logging output */
+            lam_set_file_line(file, line);
+            lam_err("Error: lam_malloc: Request for %ld bytes failed\n",
                      (long) size);
+#endif
         }
     }
 
     return addr;
 }
 
-static inline void _lam_free(void *addr, int debug_level, char *file, int line)
+
+/**
+ * Back-end error-checking free function for LAM (you should use the
+ * LAM_FREE() macro instead of this function).
+ *
+ * @param addr Address previously returned by lam_malloc()
+ * @param debug_level What debug level to use (0=none, 1=some, 2=more)
+ * @param file Typically the __FILE__ macro
+ * @param line Typically the __LINE__ macro
+ */
+inline void lam_free(void *addr, int debug_level, char *file, int line)
 {
     if (debug_level > 1 && addr == NULL) {
-        _lam_set_file_line(file, line);
-        _lam_warn("Warning: ulm_free: Invalid pointer %p\n", addr);
+#if 0
+          /* JMS Replace with logging output */
+        lam_set_file_line(file, line);
+        lam_warn("Warning: lam_free: Invalid pointer %p\n", addr);
+#endif
         return;
     }
     free(addr);
@@ -84,14 +111,34 @@ static inline void _lam_free(void *addr, int debug_level, char *file, int line)
 
 #if LAM_MALLOC_DEBUG_LEVEL > 0
 
-#define lam_malloc(SIZE) _lam_malloc(SIZE, LAM_MALLOC_DEBUG_LEVEL, __FILE__, __LINE__)
-#define lam_free(ADDR) \
-    do { _lam_free((ADDR), LAM_MALLOC_DEBUG_LEVEL, __FILE__, __LINE__); ADDR = NULL; } while (0)
+/**
+ * Error-checking malloc function for LAM.  
+ *
+ * @param SIZE Number of bytes to allocate.
+ *
+ * This macro will invoke lam_malloc() if compile-time debugging was
+ * enabled, or just invoke malloc() directly if compile-time debugging
+ * is disabled.
+ */
+#define LAM_MALLOC(SIZE) \
+    lam_malloc(SIZE, LAM_MALLOC_DEBUG_LEVEL, __FILE__, __LINE__)
 
+/**
+ * Error-checking free function for LAM.  
+ *
+ * @param ADDR Address to free.
+ *
+ * This macro will invoke lam_free() if compile-time debugging was
+ * enabled, or just invoke free() directly if compile-time debugging
+ * is disabled.
+ */
+#define LAM_FREE(ADDR) \
+    do { \
+      lam_free((ADDR), LAM_MALLOC_DEBUG_LEVEL, __FILE__, __LINE__); \
+      (ADDR) = NULL; \
+    } while (0)
 #else
-
-#define lam_malloc(SIZE) malloc(SIZE)
-#define lam_free(ADDR) free(ADDR)
-
+#define LAM_MALLOC(SIZE) malloc(SIZE)
+#define LAM_FREE(ADDR) free(ADDR)
 #endif
 #endif