[Previous Example] [Next Example] [Overview of Examples] [User's Guide]
Examples\Advanced\APD_Ring

APD Rings

Introduction

This example shows how to use the APD ring capability of Aprobe.

The "ring" is like a "rolling circular buffer" by which the newest N data files are preserved. When the N+1st file is created, the 1st is deleted, and so on.

This allows you to limit the total size of logged data, to view or delete older data while newer data is still being written, and to ensure that the newest data is always kept. A more detailed description of APD rings can be found in Chapter 4, "Multiple APD Files".

The program in this example logs a lot of data -- too much to keep it all. APD rings are designed for this type of situation. Any real time system that does not terminate and logs a lot of repetitious data would eventually fill up any on-line storage device.

This example also demonstrates how nonintrusive Aprobe can be, even when it's collecting large amounts of data from a running application.

Target Program

The target for this example is a simple program, Examples\Target\CallAlot.exe. The main() function calls subprogram a_function() many many times. And our probe will log them all, to demonstrate how Aprobe can collect large amounts of data about the program's execution. The program's source file is Examples\Target\CallAlot.c.

Writing the Probe

// Part 1
probe thread
{
   probe "a_function()"
   {
      // log the target expression "Param" every time "a_function()" is called
      on_entry 
      {
          log("Entry to a_function ", $Param);
      }
   }
}

// Part 2
static void ApdOverflowSubprogram(void)
{
   static int ApdRingFileNumber = 1;

   log("Switching to a new apd ring file #", ++ApdRingFileNumber);

   if (ApdRingFileNumber == 20)
   {
      ap_LogSnapshot(
          ap_ApdLogMethod, 
          ap_SnapshotInformationKeyword,
          "Example Snapshot at %d", ApdRingFileNumber);
   }
}

probe program
{
   on_entry
      ap_RegisterApdRingChangeCallback( ApdOverflowSubprogram );
}

Part 1 of this probe collects some data from the running program. It logs the value of parameter Param every time a_function() is called.

You'll soon see how to use a limited size APD ring of 3 APD files to store the most recent data from all these function calls. The most recently logged data will always be in the highest-numbered Hello-N.apd file, the next most recent in Hello-N-1.apd, etc. You can limit the size of the APD files with the "-s" option on the aprobe command line.

Part 2 of this probe also demonstrates the use of the APD Overflow Callback feature of Aprobe. The concept is very simple. We can register a call back routine that will get automatically called every time the APD file size limit is reached. This probe's call back is function "ApdOverflowSubprogram()".

This probe also illustrates use of the ap_LogSnapshot() feature, which can be called from any point in a probe to preserve the files belonging to the current APD ring. This in this probe, we'll see that files 19, 20, and 21 are preserved even when much newer data has been logged.

When we eventually format the data, we can either format each file in the APD ring individually, or format them all at once. To format them all at once, just specify the main APD file: Hello.apd (or just Hello) on the apformat command line.

Running The Example in the Aprobe Workspace

The Aprobe Workspace accompanying this example has an APD ring of size 3. Each APD file is 4000 bytes. This can be seen by looking at the Workspace->Application Settings... dialog.

Let's try our example:

  1. build the probe;
  2. run the program with Aprobe, and
  3. refresh the workspace.

You should now see seven APD files:

CallAlot.apd
the persistent APD file.
CallAlot-19.apd .. CallAlot-21.apd
the files preserved by ap_LogSnapshot
CallAlot-69.apd .. CallAlot-71.apd
the newest files when the program finished.
Next, format each of the APD files individually. You can easily see that CallAlot.apd-71 has the newest data (the highest numbers) and CallAlot.apd-21 has older data (lower numbers).

Notice that the data from the very beginning of the run was gone, because it was overwritten.

Running The Example From the Command Line

To use the Aprobe command line: 
   aprobe -n 3 -s 4000 -u Hello.dll ..\..\Target\CallAlot.exe
   apformat CallAlot

This apformat command formats all of the APD ring files (from oldest to newest), so you'll see all the data.

Summary

From this example you have learned:
[Previous Example] [Next Example] [Overview of Examples] [User's Guide]