Aprobe Demo

Just Probe It

Start the demo by running Trace, one of Aprobe's Predefined Probes. If you have any problems, e-mail support@ocsystems.com or call us at +1 703 359 8160.

The program being probed is Demo.c, which just does a few memory allocations and sleeps the rest of the time. There is nothing special about Demo.c; it could be any program. We have compiled it for you as a convenience into Demo.exe, and the Aprobe Workspace file is pointing to it.

Execution Tracing

  1. Right-click on "Demo.exe" at the top of the workspace tree on the left;
  2. Choose Predefined Probes->Trace to bring up the Predefined Probes option dialog (we'll just take the defaults);
  3. Click "Ok", and Demo.exe will be run in a command prompt window.
    Aprobe will monitor it as it runs, and save the trace data in a file.
  4. After Demo.exe has finished running, close the command prompt window.
  5. The Aprobe Windows GUI will automatically format the trace data and display the results in a text window.
    There were a lot of calls for a little program!

Memory Allocation

Now, run Memwatch, another of Aprobe's Predefined Probes:
  1. Right-click on "Demo.exe";
  2. Choose Predefined Probes->Memwatch to bring up the Predefined Probes option dialog;
  3. Click Ok, and Demo.exe will be run under Aprobe in a command prompt window.
  4. See the "Running Demo" command prompt window, and then another window containing two graphs.
  5. Click the "Close" button in the graph window when you're finished looking at it.
  6. Close the command prompt window.
  7. The formatted results then appear. It reports on all memory that remains allocated at the end of the program.

Performance Profiling

It's easy to apply each predefined probe to your program this way.

Try this next: use Profile to see why Demo.exe takes so long. After closing the "Running Demo" window, the formatted output shows that we're spending 99% of our time in "DoSleep"! Exercise for the reader: Edit the Application Options to pass a 0 (zero) command-line argument to Demo.exe to eliminate the sleeping.

The above should have taken less than fifteen minutes. If you ran into any problems, please contact support@ocsystems.com (or call us at +1 703 359 8160).

What You Just Did

The above can also be accomplished from the command-line. It's just as easy, so next we'll discuss how.

The predefined probes are:

The above steps led through all of these except for Coverage, which we show below, where we will run a small "custom" probe in combination with the predefined line coverage probe to get 100% test coverage.

Each predefined probe has a similar interface. Where substantial configuration is available, the user can request a Java GUI with which to specify the configuration. The configuration is defined in a readable file with an extension of ".cfg", and you can directly edit that file to change options if you decide not to use the GUI. However, each probe has a good set of defaults to allow you to use it "out-of-the-box", as we did above.

To run the above probes from the command-line, you would enter:

aprobe -u trace Demo.exe
apformat Demo.apd

aprobe -u memwatch -p -g Demo.exe 
apformat Demo.apd

aprobe -u profile Demo.exe
apformat Demo.apd

These predefined probes are just the beginning. You can write your own custom probes, as described in the next section.

Custom Probes

The predefined probes that you have seen provide useful capabilities in an easy to use manner. Aprobe also provides the capability to write custom probes specific to your application. This portion of the demo will demonstrate this.

Examine the file "Demo.apc", reproduced below. 

//
// This apc file will force the malloc call to return a NULL value 
// (indicating no more memory available) after malloc is called five
// times from within AllocateOne.
//

int count = 0;

probe thread
{
  probe extern:"AllocateOne()" 
  {
    probe extern:"malloc()" 
    { 
      on_entry
        count++;

      on_exit
        if (count > 5)
          $return = NULL;
    }
  }
}

The aprobe patching language is C, with a few extra keywords added (probe, on_entry, on_exit and on_line). The "patches", or probes, that are defined in Demo.apc have already been compiled for you as a convenience, producing Demo.dll. These probes cause malloc to return a zero (null pointer) after it is called the fifth time from within the routine AllocateOne. In the demo, this will cause a different path to be executed, so we can test that path.

Run the demo with this probe: right click on Demo.exe again and select the first option, "Run Demo.exe with Aprobe". A window should appear and it should contain the output produced by the Demo.exe being run under Aprobe with the patches specified in Demo.apc.

Note that the patches cause malloc to return NULL as expected and the demo program to print out that it is out of memory. To run this from the command line:

   
aprobe -u Demo Demo.exe

Combining Predefined and Custom Probes

Now, let's verify that all lines in the demo have been executed. First, run the coverage predefined probe on Demo.exe, as described in the first part of demo:
  1. Right-click on Demo.exe
  2. Select Predefined Probes -> Line Coverage
  3. Click Ok.
  4. Close the command-line in which the aprobe command is run
Near the bottom of the coverage report in the "Demo-0.apd" window it says: 
  Percent of lines executed:  85
  The following probed lines were not executed:
    Lines: 31 .. 32 (demo.c)
Now let's run it again for the "Out of memory" case. To do this we run the line coverage probe again, but this time, we will add the Demo UAL, so both the Demo and coverage probes are applied (one can use many different probes at one time!)
  1. Right-click on Demo.exe
  2. Select Predefined Probes -> Line Coverage
  3. Click the "Edit Application Options" button
  4. In the "Aprobe Options" part of the "Application Settings" dialog, change the "APD Filename" to "Demo2", and enter "-u Demo" under "Additional Settings"
  5. Click Ok to complete the Application Settings dialog
  6. Click Ok in the "Tracing, Profiling..." dialog to run the application.
  7. Close the command-line in which the aprobe command is run
From the command line, this would be run as: 
aprobe -u coverage Demo.exe
apformat Demo
aprobe -u coverage -u Demo -d Demo2 Demo.exe
apformat Demo2
There should now be a "Demo2-0.apd" window within Aprobe, which contains the results of this second run with both coverage and demo together. Looking near the bottom of this second report, we see that this time a different span of lines was not executed.

The results of these two runs can be merged into a summary report using the atcmerge tool as shown in the Aprobe\Advanced\Test_Coverage example.

Of course, custom probes can do much more than this demo shows. If you want to get an idea of what they can do, we suggest that you try the Example Workspaces found in the File menu and described in Aprobe\Examples.

For other information, including white papers, visit www.aprobe.com or contact sales@ocsystems.com.