Simple Example 
 
Here we will show a simple example of how to use C Memory Scavenger
 
This example is a console application. It allocates some memory, and intentionally, "forgets" to free it. These allocations will be found by the Monitor. Here is the code, which we assume is put in a file called Simple.c, also found in the downloadable Development Kit
 
Code List of Simple.c 
 
#include <string.h> 
#include "CMemScav.h"   // Line 2 
 
int main(int argc, char* argv[]) 
 char *str1; 
 char *str2; 
 char *str3; 
 
 // Initialize CMemScav: enable CMemScav, skip logging and choose the default port 5913 
 // ----------------------------------------------------------------------------------- 
 CMemScavInit(TRUE, FALSE, NULL, 5913); // Line 12 
 
 // Allocate and use some memory 
 // ---------------------------- 
 str1 = (char*)malloc(100); // Line 16 
 strcpy(str1, "Hello World!"); 
 
 str2 = (char*)calloc(1, 200); // Line 19 
 strcpy(str2, "Use some zero initialized memory."); 
 
 str3 = strdup(str2); // Line 22 (duplicates 34 bytes, trailing zero included) 
 
 // Now watch these allocations from the Monitor, using the 'Analyze' part 
 // ---------------------------------------------------------------------- 
 printf("Now, before going on...\n");      // Line 26 
 printf("o Launch the Monitor\n");         // Line 27 
 printf("o Connect to the application\n"); // Line 28 
 printf("o Get summary snapshot\n");       // Line 29 
 printf("o Get list of allocations\n\n");  // Line 30 
 
 // Using the 'Analyze' part of the Monitor, we saw exactly where 3 memory 
 // allocations were done. Using this knowledge, suitable places to clean up 
 // these allocations could be found, for example, below. 
 // However, let's skip freeing memory here, to demonstrate the next part of 
 // the Monitor. 
 // ------------------------------------------------------------------------ 
/* 
 free(str1); // Line 39 
 free(str2); // Line 40 
 free(str3); // Line 41 
*/ 
 
 // Use the 'Synthesize' part to generate clean up code 
 // --------------------------------------------------- 
 printf("o Make sure neither 'Regardless of file name' nor\n"); // Line 46 
 printf("  'Only the calling thread' is checked, and that\n"); 
 printf("  'The exact line', 'The exact size', and 'All indexes'\n"); 
 printf("  all are selected.\n"); 
 printf("o Generate C Memory Scavenger code\n");                // Line 50 
 printf("o Have a look at the generated 'Code Lines'\n");       // Line 51 
 printf("o Check 'Regardless of file name' and select both\n"); // Line 52 
 printf("  'All lines' and 'All sizes'.\n"); 
 printf("o Generate C Memory Scavenger code one more time\n");  // Line 54 
 printf("o Save the code to a file and pretend this was copied into the code below.\n"); 
 
 // Here is the code the 'Synthesize' part generated at line 62 
 // which will free all outstanding memory allocations 
 // ----------------------------------------------------------- 
 printf("Hit ENTER to let CMemScav free all outstanding memory allocations...\n"); 
 getchar();   // Line 61 
 CMemScavFreeAll(); // Line 62 
 
 // Check that the call above really worked 
 // --------------------------------------- 
 printf("o Now get another list of allocations from inside the Monitor\n"); // Line 66 
 printf("o Note that the list now is empty\n\n");                           // Line 67 
 
 printf("Hit ENTER to exit the application...\n");                          // Line 69 
 getchar(); // Line 70 
 
 // Finish the usage of CMemScav (which will free internal memory used) 
 // ------------------------------------------------------------------- 
 CMemScavFinish(); // Line 74 
 return 0; 
 
Comments about the code 
 
  • To use C Memory Scavenger, a header file needs to be included, CMemScav.h (line 2). 
  • C Memory Scavenger is initiated with a call to CMemScavInit (line 12). 
  • Three memory allocations are done, using malloc, calloc, and strdup, respectively (lines 16, 19 and 22). 
  • Some calls to printf are done, describing what is happen and how to use the Monitor (lines 26-30, 46-55, 60,  and 66-69). 
  • Three calls to free, which are intentionally left out (lines 39-41). 
  • A call to CMemScavFreeAll(), which will release all outstanding memory allocations. In this case, this means the three calls mentioned above (line 62). 
  • A call to CMemScavFinish(), which will free some internal memory used by C Memory Scavenger (line 74). 
  •  
    Let's run both the application and the Monitor, to see how they work together 
     
  • Launch the Monitor and the application, that is, Simpe.c compiled and linked with the CMemScav library - regardsless of order. 
  • The application will halt at the first call to getchar(), i.e., at line 61. Follow the instructions given in the console window, which also is described in more detail below. 
  • In the Monitor, click at "ringing phone" button to connect to the application. Using the default IP Address 127.0.0.1 means that the application is assumed to be run at the same computer as the Monitor. If the application is running on any other computer, enter its IP address. Now a socket connection should be established between the two programs (if the "ringing phone" button become disabled and the "hangup phone" become enabled, the connection is up). Note that any firewall running, might prevent this connection from being established. Perhaps you need to switch off such a firewall, or open up the used port 5913 to let your application and the Monitor talk to each other. 
  • Click at the camera button (not the video button), and values pop up in the frame "Summary of Allocations" down to the left in the first screen shot below. The Monitor asked the application of a summary and the application returned this data. Since we only did one call each to the three memory allocation functions, we can easily see that the summary is correct. 
  • Next, click at the "table" button, the one looking like a table up to the left in the frame "Detailed List of Outstanding Memory Allocations" down to the right in Monitor. The list below this button is filled with three lines. Here we get more precise information about the allocations. File names and line numbers are presented, together with some other information. For example, we can see here that all allocations were done from the same thread, since the thread ids are the same. 
  • Now click at the "write code" button, looking like a-notepad-with-a-hand-holding-a-pencil, and three "Code Lines" pop up in the "Synthesize"-frame, with calls to a CMemScavFreeThese function. The first line is (the path in the first argument depends on where the source code was when compiling): CMemScavFreeThese("C:\\CMemScav\\src\\Simple.c", 16, 16, 100, 100, 0, 0, 0); This means that if a memory allocation has been done (and not freed) in the file C:\CMemScav\src\Simple.c at line 16, of 100B, this memory will be freed by inserting this line anywhere in the application (after the allocation). Those eight arguments to this function can be used to fine tune how to free specific parts of the memory. Much more about this later.  
  • Of course, the best way to solve the memory leaks in this little exampe, is to re-insert the three lines 39-41, here intentionally left out. However, remember that this is a small example and finding the right places for these free calls may be much harder in a real situation. Many times, the memory pieces are allocated in other functions than they are used in. 
  • By choosing different settings in the Synthesize frame, the Monitor can create calls to the library that will free selected part of the memory lines in the "Detailed List...". Much of the work in mastering C Memory Scavenger is to create such calls and place them into the applications, but this is generally much easier than finding the precise free calls that traditionally have to be created. 
  • Check the check box 'Regardless of file name' and select the radio buttons 'All lines' and 'All sizes'. Click at the "write" button again and now the single line CMemScavFreeAll(); appears. This is line 62 in the source code. All applications should be able to do this call right before they exit. However, this place is a bit too late many times. 
  • Finally, hit any key in the console window and the application will run the call in the item above, and pause at the next getchar() statement, at line 70. Check the summary or the detailed list to see that the three allocations are now removed, see the next screen shot below. This concludes the first example. 
  •  
     
     
     
    Above: Screen shot showing the Monitor having caught the outstanding allocations and suggested three code lines to fix the problems. 
     
     
     
     
     
    Above: Screen shot showing the Monitor summing up the result after a call to CMemScavFreeAll().