ARM 4 Python Language Tutorial - Introduction

Here's a variant on the Kernighan and Richie classic:

#!/usr/bin/env python

import arm4

# Register
app_id = arm4.register_application ("HelloWorld")
tran_id = arm4.register_transaction (app_id, "HelloTran")

# Start our application and transaction measurements
app_handle = arm4.start_application (app_id, "Example")
tran_handle = arm4.start_transaction (app_handle, tran_id)

# Do our work
print 'Hello, world!'

# Stop our measurements
arm4.stop_transaction (tran_handle) # Default status is arm4.ARM_STATUS_GOOD
arm4.stop_application (app_handle)

# Finish up
arm4.destroy_application (app_id)

While this adds a lot to a simple program, you'll find that it doesn't add much more to a more complex one. To understand what's going on, let's look at the steps involved.

The first element of note is the inclusion of the ARM 4 Python module.

import arm4

This includes the function declarations and constants you'll use in all ARM 4 instrumented programs.

Registration

The next stage of instrumentation is registration.

# Register
app_id = arm4.register_application ("HelloWorld")
tran_id = arm4.register_transaction (app_id, "HelloTran")

As you'll recall from our concepts tutorial, transactions are part of an application, and applications are composed of transactions. In this case, we're declaring a basic application called "HelloWorld". As it's registered, an identifier is returned in app_id. If the application had been registered previously, then the same identifier is returned. It's possible to register the same application in multiple programs. As long as the parameters are the same, they'll all return the same application identifier even though their transactions might be quite different.

We then register our transactions indicating that their part of our application by passing in the app_id we were given when the application was registered. We can have any number of transactions associated with the application. In this case there's only one which we've called "HelloTran". It's identifier is returned as tran_id. As with applications, re-registering a transaction with the same parameters will return the same identifier.

As far as the ARM 4 agent is concerned, we've still got nothing to measure. These registrations give the application some idea about what's going to happen, but there's still no action.

Instantiation

We need instances of our applications or transactions. Registration only needs to happen once, but a new instance is created every time an application or transaction is begun.

app_handle = arm4.start_application (app_id, "Example")

This starts the application. Typically, there will only be one application instance per program, although there may be cases where this isn't true (such as multi-threaded programs which may have an instance per thread.) Starting an application instance returns a handle, app_handle, which is required to perform operations on the application instance.

Next we create an instance of the transaction.

tran_handle = arm4.start_transaction (app_handle, tran_id)

This starts the clock. As far as the agent is concerned, work has now begun. Like the application instance, the transaction instance returns a handle, tran_handle, that is used to control it's operation. Unlike the application handle, it's expected to have many of these over the life of the program even though our example only has one.

Get to Work!

This is the focus of our instrumentation. While not part of our arm specification, this is what we are actually measuring.

print 'Hello, world!'

Complete the transaction

Once the actual work has completed, we need to notify the agent that the transaction has completed and that the measurement should be taken.

arm4.stop_transaction (tran_handle) # Default status is arm4.ARM_STATUS_GOOD

As mentioned earlier, we use the tran_handle to tell the agent which transaction is completing. It's possible to have many transactions active concurrently so it's not enough to assume the last created will be the first to complete.

Clean Up

When all our transactions are completed and we're not going to create any further instanced, we need to tell the agent that our application instance is also complete.

arm4.stop_application (app_handle)

Any transactions that were still in progress will be marked as aborted.

Finally, we should clean up after ourselves and release any resources allocated by the agent.

arm4.destroy_application (app_id)

This typically won't wipe the definition from the database, but it may wipe it from memory.

Compiling, Linking, and Running

Ah, the magic of Python! No compiling, no linking, just running!

$ python arm4_hello.py
Hello, world!