Martini External Control Interface

Table of Contents

  1. Introduction
  2. External Control Module Initialization
  3. External Control Callback Registration
  4. Generating External Control Events

Introduction

Most profiling tools are comprised of two layers, usually implemented as two separate processes:
  1. The Profiler back-end: a module (usually a dyanamically-linked library) loaded into the virtual machine process executing the profiled application. The back-end is responsible for monitoring the application and collecting profiling data. All MPI clients can be considered as back-end modules.
  2. The Profiler front-end: a standalone application which implements the tool's user interface and enables the user to interact with the profiler back-end.

The Martini External Control Interface is designed to allow Profiler front-ends to interact with their MPI back-end modules by sending "control" messages that will be dispatched to the MPI back-end modules as MPI events.

To interact with MPI clients, a tool implements an "External Control" module which is loaded into the virtual machine process together with the MPI client it needs to control. This External Control module serves as a bridge between the tool's front-end process and the MPI client back-end and enables the front-end to send certain MPI events to the MPI client.

The following figure outlines the relationship between the tool's front-end, the External Control module, and MPI Client and the profiled application.

ECOverview.png

Martini External Control

It is important to note that the Martini External Control Interface does not provide nor define any services for the tool's front-end to interact with its External Control module. It only enables the External Control module to deliver messages to the MPI client as MPI events.

A Martini External Control module is expected to implement and export the following functions defined in the MartiniExternalControl.h header file:

  1. EC_Init : invoked by the Martini runtime during Virtual Machine initialization to initialize the External Control module
  2. RegisterMartiniCallback : invoked by the Martini runtime when an MPI client registers for an External Control event
  3. MartiniProcessShutdown : invoked by the Martini runtime just before the virtual machine shuts down
  4. MartiniMessage : invoked by the Martini runtime when certain error conditions occur.

External Control Module Initialization

The Martini External Control module library is loaded by the Martini runtime, according to its configuration (TBD). Once the External Control module is loaded, its EC_Init entry-point function is called. The module is expected to initialize itself in the context of the EC_Init function and to establish the communication channel with the tool's front-end. When EC_Init completes, execution returns to the Martini runtime and the Virtual Machine process continues its initialization.

External Control Callback Registration

When an MPI client registers for an external control event, the Martini runtime invokes the RegisterMartiniCallback function of the External Control module and hands it a callback function pointer. The External Control module can then use this function pointer to generate the an MPI event to be delivered to the loaded MPI client.

Generating External Control Events

When the External Control module needs to send a notification to the MPI Client, it uses the Martini callback function that corresponds to the event it wants to generate.

The following External Control events are supported:

Remarks:
Except for the Set Output Directory event, the External Control events are not interpreted by the Martini runtime in any way, and delivered as-is to any MPI Client which registered for these events. Therefore, the true meaning of these events should be determined and agreed by both the External Control module and the MPI Client it controls. It is recommended, however, that the External Control module will follow the meaning of the External Control events as described in the documentation. This will allow the module to correctly interact with any MPI Client which also follow these guidelines.


Generated on Thu Mar 6 15:07:55 2008 for Martini by doxygen 1.5.5