Dynamic Probe Class Library Programming Guide

Chapter 10. Creating data callback routines

As described in Step 2e: Create probe expressions to represent function calls, a probe expression can send data back to the analysis tool by calling the DPCL system-defined function Ais_send. Step 1: Create probe module function also describes this built-in function, and shows how it can be called within a probe module function. If the probe expression created by the analysis tool calls the Ais_send function (or calls a probe module function that in turn calls Ais_send), then the analysis tool code must contain a data callback function that will handle the data that the Ais_send function will send.

At run time, the callback function will be invoked once for each data message sent from the probe. What's more, if the same probe is executed from within multiple processes, each data message from each process will trigger the same data callback.

The function prototype for a callback is:

void callback (

     GCBSysType sys,

     GCBTagType tag,

     GCBObjType obj,

     GCBMsgType msg);

 

Where:

is:

sys

a data structure defined as

struct GCBSysType {

     int msg_socket;

     int msg_type;

     int msg_size;

};

 

Where

Is

msg_socket

the socket or file descriptor from which the message was received.

msg_type

a message key or type value that represents the protocol or purpose behind the message. This is provided and used by the DPCL system in order to determine the callback routine to execute.

msg_size

the size of the message in bytes.

tag

a value, large enough to contain a pointer, that is supplied by the analysis tool when the callback associated with the probe is identified. If the probe is executed by the analysis tool as:

• a point probe, then the callback and its associated tag are identified (as described in Installing and activating point probes) when the analysis tool calls the Process::install_probe, Process::binstall_probe, Application::install_probe, or Application::binstall_probe function.
• a phase probe, then the callback and its associated tag are identified (as described in Executing phase probes) when the analysis tool uses a constructor to create the Phase class object.
• a one-shot probe, then the callback and its associated tag are identified (as described in Executing one-shot probes when the analysis tool calls the Process::execute, Process::bexecute, Application::execute, or Application::bexecute function.

The tag parameter allows the analysis tool to use the callback function for more than one purpose. For example, the tag may contain a pointer to relevant data that changes from one execution of the callback to another.

obj

a pointer to the object that issued the request. In the case of the Application object, the requesting object will be the Process object managed by the Application object. The DPCL system supplies this information because each data message from a probe triggers the same data callback, even when the probe is executed from within multiple processes. By supplying a pointer to the invoking object, the DPCL system enables the callback to respond differently depending on the invoking object.

msg

a pointer to the message content. The actual content of the message is presented as a raw byte stream. The size of the message is stored in sys.msg_size. The format of the message is determined by the probe, and contains whatever data the probe supplied to the Ais_send function.

For example, the following code defines a callback for a simple pass counter. The installed probe calls Ais_send, supplying it with the count. This callback then identifies the program task (by using the pointer to the invoking Process and the Process::get_task function), and prints the task and count information to standard output.

void count_cb(GCBSystType sys, GCBTagType tag, GCBObjType obj, GCBMsgType msg)

{

  Process *P = (Process *) obj;

  int *count = (int *) msg;

  int task = P->get_task();

 

  printf("task %d count = %d\n", task, *count);

}

For more information on the Ais_send or Process::get_task functions, refer to their UNIX man pages, or their entries in the DPCL Class Reference.