Calling it quits measuring

 

Now that we have come so far we can start running the examples. Four examples were created to show the usage of the class QSimpleArmTran.

If the two first examples do not look familiar to you, have a look at the Qt Tutorial, Chapter 2 and 14. There you can see the originals we derived from. We assume that you are familiar with Qt and their well-known signal/slot mechanism.

This example shows how to use the class QSimpleArmTran in a very simple case. You get a small widget with a "Quit ARM Measurement" button which quits the application when you press it. The time elapsed between application start and the push on the button is measured.

Source code

    #include <QApplication>
    #include <QFont>
    #include <QPushButton>

    #include <QSimpleArmTran>

    int main(int argc, char *argv[])
    {
      QApplication app( argc, argv );
      QSimpleArmTran arm("Calling it quits ARM");
  
      arm.start();

      QPushButton quit("Quit ARM Measurement", 0);
      quit.resize(300, 30);
      quit.setFont( QFont("Times", 18, QFont::Bold));
  
      QObject::connect( &quit, SIGNAL(clicked()), &app, SLOT(quit()) );
      QObject::connect( &quit, SIGNAL(clicked()), &arm, SLOT(stop()) );
  
      quit.show();
      return app.exec();
    }

Line-by-line walkthrough

The non-ARM related lines were already discussed in the tutorial by Trolltech. The first line of interest is

    QSimpleArmTran arm("Calling it quits ARM");

Here a transaction definition called Calling it quits ARM is instantiated. The name describes our transaction and should be self-describing. It will be used later on when the transactions are analysed. See chapter "How to proceed" for details on how to analyse measurement results with the MyARM management tools.

The next line of code starts measuring the transaction:

    arm.start();

This will start an internal timer within the ARM implementation. The timer is executed until:

    arm.stop()

is called. This method is called here using the Qt signal/slot mechanism:

    QObject::connect( &quit, SIGNAL(clicked()),&arm, SLOT(stop()) );

The stop() method is called at the time when the quit-button is pressed. This is exactly the time just before the application is terminated (in case the button is released right after clicking it). Our QSimpleArmTran object will measure the time between calling start() and stop(). These methods were called just once, so we will have just one measured transaction instance. Theoretically these methods can be called as often as you want, resulting in many transaction instances. For a differentiation between transaction definitions and transaction instances see excursus in chapter "Facing the wall" . The result (one transaction instance) can then be viewed with the manager tools delivered with your ARM software (e.g. MyARM Evaluation Edition). For a detailed description on how to proceed from here see chapter "How to proceed" .

Compiling

The code can be compiled using the standard Qt qmake mechanism. Just go into the directory tutorial/t1 and say:

    qmake
    make

Behaviour

The program will behave exactly as the program described in the Trolltech tutorial chapter 2. The only differences are that the text of the button is a bit longer and that you will know how long it took from initialising the application to pressing the button.

All ARM specifics are hidden in QSimpleArmTran, i.e. an ARM application is started automatically when the first ARM transaction is instantiated. For a deeper understanding of ARM applications and ARM transactions have a look at the following excursus .

E x c u r s u s

Applications and transactions An ARM application is a logical unit (like a "namespace") and can be congruent with your implemented program, although it need not necessarily be the same. Imagine a multi-threaded program, where each thread is modelled as a different ARM application. How many ARM applications one program hosts is an architectural decision. For now we only know programs that instantiated one ARM application. ARM transactions are code snippets (e.g. functions or methods) that have a definite start and end point. A transaction can call a sub-transaction (e.g. again a function or a method) which calls another sub-transaction and so forth, building a "transaction chain". A transaction is identified as a sub-transaction in case it knows the so called "correlator" of its parent. A correlator is a opaque byte array that uniquely identifies a running transaction and is created by the respective ARM functions that are called during transaction start. The first (parent) transaction in a chain finishes when the last of their sub-transactions has finished. This will have needed a certain amount of time and is therefore an indicator for the parent transactions "performance". Since ARM measures the time for each transaction separately the slowest child is easily identified.