Advice to metric authors

There are two main issues to keep in mind when writing a metric plugin library:

• Speed

• Async-signal safety

Linaro MAP aims to avoid adding overhead to the runtime of the program that it profiles. The insertion of a comparatively small amount of overhead can get magnified when MPI communications between a large number of processes are taken into account. For this reason, metric getters must return values as fast as possible, and Linaro recommends avoiding long-running operations unless in the allinea_plugin_initialise() or allinea_plugin_cleanup() functions.

Linaro MAP does its sampling from inside a signal handler. This signal might interrupt any operation, including basic C library functions such as malloc or printf. It is possible for a signal to interrupt an operation in such a way that for the duration of the signal handler some data structures are left in an inconsistent state. If the code in the signal handler then uses such a data structure (for example, makes another malloc call) then the program could deadlock, crash, or otherwise behave in an unpredictable way. To prevent this, code called in a metric plugin getter method must avoid making any function calls that are not async-signal safe (allocating memory being the prime example). For convenience, the Metric plugin API includes versions of many common functions that are safe to use inside signal handlers (and subsequently, from metric getter functions).

See the example metric plugin implementation custom1.c and the corresponding definition file custom1.xml.