From cff6206277a774428510d19f468568279305ec9e Mon Sep 17 00:00:00 2001
From: "Steven R. Loomis" <srl@icu-project.org>
Date: Tue, 24 Jul 2012 17:33:19 +0000
Subject: [PATCH] ICU-9544 update javadocs around ctst_malloc

X-SVN-Rev: 32055
---
 icu4c/source/test/cintltst/cintltst.c | 28 ++++++++++++++--------
 icu4c/source/test/cintltst/cintltst.h | 34 ++++++++++++++++++++++-----
 2 files changed, 46 insertions(+), 16 deletions(-)

diff --git a/icu4c/source/test/cintltst/cintltst.c b/icu4c/source/test/cintltst/cintltst.c
index 52d274c215b..4d946dfe03f 100644
--- a/icu4c/source/test/cintltst/cintltst.c
+++ b/icu4c/source/test/cintltst/cintltst.c
@@ -1,6 +1,6 @@
 /********************************************************************
  * COPYRIGHT:
- * Copyright (c) 1997-2011, International Business Machines Corporation and
+ * Copyright (c) 1997-2012, International Business Machines Corporation and
  * others. All Rights Reserved.
  ********************************************************************/
 /********************************************************************************
@@ -41,9 +41,17 @@
 #   include <console.h>
 #endif
 
+#define CTST_MAX_ALLOC 8192
+/* Array used as a queue */
+static void * ctst_allocated_stuff[CTST_MAX_ALLOC] = {0};
+static int ctst_allocated = 0;
+static UBool ctst_free = FALSE;
+static int ctst_allocated_total = 0;
+
 #define CTST_LEAK_CHECK 1
+
 #ifdef CTST_LEAK_CHECK
-U_CFUNC void ctst_freeAll(void);
+static void ctst_freeAll(void);
 #endif
 
 static char* _testDataPath=NULL;
@@ -210,6 +218,10 @@ int main(int argc, const char* const argv[])
         ctst_freeAll();
         /* To check for leaks */
         u_cleanup(); /* nuke the hashtable.. so that any still-open cnvs are leaked */
+        
+        if(getTestOption(VERBOSITY_OPTION) && ctst_allocated_total>0) {
+          fprintf(stderr,"ctst_freeAll():  cleaned up after %d allocations (queue of %d)\n", ctst_allocated_total, CTST_MAX_ALLOC);
+        }
 #ifdef URES_DEBUG
         if(ures_dumpCacheContents()) {
           fprintf(stderr, "Error: After final u_cleanup, RB cache was not empty.\n");
@@ -612,13 +624,9 @@ U_CFUNC void ctest_resetTimeZone(void) {
 #endif
 }
 
-#define CTST_MAX_ALLOC 8192
-/* Array used as a queue */
-static void * ctst_allocated_stuff[CTST_MAX_ALLOC] = {0};
-static int ctst_allocated = 0;
-static UBool ctst_free = FALSE;
 
 void *ctst_malloc(size_t size) {
+  ctst_allocated_total++;
     if(ctst_allocated >= CTST_MAX_ALLOC - 1) {
         ctst_allocated = 0;
         ctst_free = TRUE;
@@ -630,14 +638,14 @@ void *ctst_malloc(size_t size) {
 }
 
 #ifdef CTST_LEAK_CHECK
-void ctst_freeAll() {
+static void ctst_freeAll() {
     int i;
-    if(ctst_free == 0) {
+    if(ctst_free == FALSE) { /* only free up to the allocated mark */
         for(i=0; i<ctst_allocated; i++) {
             free(ctst_allocated_stuff[i]);
             ctst_allocated_stuff[i] = NULL;
         }
-    } else {
+    } else { /* free all */
         for(i=0; i<CTST_MAX_ALLOC; i++) {
             free(ctst_allocated_stuff[i]);
             ctst_allocated_stuff[i] = NULL;
diff --git a/icu4c/source/test/cintltst/cintltst.h b/icu4c/source/test/cintltst/cintltst.h
index 5ef9176416e..a4755396192 100644
--- a/icu4c/source/test/cintltst/cintltst.h
+++ b/icu4c/source/test/cintltst/cintltst.h
@@ -1,6 +1,6 @@
 /********************************************************************
  * COPYRIGHT: 
- * Copyright (c) 1997-2011, International Business Machines Corporation and
+ * Copyright (c) 1997-2012, International Business Machines Corporation and
  * others. All Rights Reserved.
  ********************************************************************/
 /********************************************************************************
@@ -41,21 +41,43 @@ U_CFUNC const char* ctest_dataOutDir(void);
  */
 U_CFUNC const char* ctest_dataSrcDir(void);
 
+/**
+ * Convert a char string into a UChar string, with unescaping
+ * The result buffer has been malloc()'ed (not ctst_malloc) and needs to be free()'ed by the caller.
+ */
 U_CFUNC UChar* CharsToUChars(const char* chars);
 
 /**
  * Convert a const UChar* into a char*
- * Caller owns storage, but in practice this function
- * LEAKS so be aware of that.
+ * Result is allocated with ctst_malloc and will be freed at the end of the test.
  * @param unichars UChars (null terminated) to be converted
  * @return new char* to the unichars in host format
  */
  
 U_CFUNC char *austrdup(const UChar* unichars);
-U_CFUNC char *aescstrdup(const UChar* unichars, int32_t length);
-U_CFUNC void *ctst_malloc(size_t size);
-U_CFUNC void ctst_freeAll(void);
 
+/**
+ * Convert a const UChar* into an escaped char*
+ * Result is allocated with ctst_malloc and will be freed at the end of the test.
+ * @param unichars UChars to be converted
+ * @param length length of chars
+ * @return new char* to the unichars in host format
+ */
+U_CFUNC char *aescstrdup(const UChar* unichars, int32_t length);
+
+/**
+ * Special memory allocation function for test use. At the end of cintltst, 
+ * or every few thousand allocations, memory allocated by this function will be freed.
+ * Do not manually free memory returned by this function, and do not retain a pointer
+ * outside of a single instruction scope (i.e. long enough to display the value).
+ * @see #ctst_freeAll
+ */
+U_CFUNC void *ctst_malloc(size_t size);
+
+/**
+ * Return the path to cintltst's data ( icu/source/data/testdata ) directory. 
+ * Return value is allocated by ctst_malloc and should not be deleted.
+ */
 U_CFUNC const char* loadTestData(UErrorCode* err);
 
 /**