Dynamic Probe Class Library Programming Guide

There are two relationships that an analysis tool can establish with a
target application process in order to affect its execution. The
analysis tool can "connect" to the process, and, once connected, can also
"attach" itself to the process. Connection (described in detail in Chapter 6, Connecting to or starting the target application processes) establishes a communication channel to the host where the
process resides and creates the environment within the process that allows the
analysis tool to insert and remove instrumentation probes. Inserting
instrumentation probes enables the analysis tool to indirectly influence the
execution of a target application process.

An analysis tool can connect to processes either by explicitly connecting
(by calling the connect or bconnect function of either
the Process or Application class), or by creating them
(by calling the create or bcreate function of either the
Process or PoeAppl class). The connect
and bconnect functions place the process(es) in a connected state
represented by the enumeration constant PRC_connected of the
Process class' ConnectState enumeration
type. The create and bcreate functions place the
process(es) in a created state represented by the enumeration constant
PRC_created of the Process class'
ConnectState enumeration type. A subsequent call to the
start or bstart function will move the process(es) into
the PRC_connected state. In either case, however, a
connection has been established that enables the analysis tool to instrument
the target application process(es) with probes.

When a process is connected (in either the PRC_connected or
PRC_created state), the analysis tool can attach to the process
using the attach or battach function of either the
Process or Application class. Attaching to the
process enables the analysis tool to control execution of the process
directly. This direct process control is exclusive -- no other
analysis tool will be able to attach to the process. The following
sections describe how an analysis tool can:

attach to one or more connected processes by calling the
Process::attach,
Process::battach,
Applcation::attach, or
Application::battach function.

resume execution of one or more suspended processes by calling the
Process::resume,
Process::bresume,
Application::resume, or
Application::bresume function.

detach itself from one or more target application processes whose
execution it no longer needs to control. Since only one analysis tool
can be attached to a process at a time, it is important that your analysis
tool detach itself from any process it no longer needs to control. To
do this, the analysis tool uses the Process::detach,
Process::bdetach,
Application::detach, or
Application::bdetach function.

The analysis tool can also terminate a process. If the process is in
the PRC_created state, the analysis tool does not need to attach to
it in order to terminate its execution. If the analysis tool has, on
the other hand, not created but merely connected to a remote process, it must
attach to the process in order to terminate it. The analysis terminates
one or more processes by calling the Process::destroy,
Process::bdestroy,
Application::destroy, or
Application::bdestroy function.

In order to attach itself to one or more target application processes, the
analysis tool must be connected to the process(es) as described in Connecting to the target application. In other words, the Process object must
be in either the PRC_connected or PRC_created
state; the analysis tool can query a Process object's
state by calling the Process::query_state
function.

To attach to a single process, the analysis tool can use the asynchronous
function Process::attach or its blocking equivalent
Process::battach. To attach to processes on an
application-wide basis (for all Process objects managed by an
Application object), the analysis tool can use the functions
Application::attach or
Application::battach.

Attaching to a process puts the process in an attached state represented by
the enumeration constant PRC_attached of the Process
class' ConnectState enumeration type. The analysis tool
can query a Process object's state by calling the
Process::query_state function.

Once attached to one or more target application processes, the analysis
tool can:

Note that only one analysis tool can be attached to a particular process at
a time. For this reason, an analysis tool may want to "detach" itself
from a particular process when it no longer needs to directly control its
execution. To do this, see Detaching from target application processes.

For more information on the Process::attach,
Process::battach,
Application::attach, and
Application::battach functions, refer to their UNIX man
pages or their entries in the DPCL Class Reference.

When the analysis tool attaches to one or more target application processes
(as described in Attaching to the target application process(es)), execution of the process(es) is temporarily
suspended. By suspending a process when the analysis tool attaches to
it, the DPCL system enables the analysis tool to perform actions on it before
resuming its execution. If the analysis tool were a debugger, for
example, this would enable it to examine the processes state. Also, an
analysis tool could install probes into the target application (as described
in Chapter 9, Executing probes in target application processes) before resuming its execution. Once the analysis
tool has resumed execution of a process, it can explicitly suspend its
execution again as described in Suspending execution of the target application process(es).

To resume execution of a single suspended process, the analysis tool can
use the asynchronous function Process::resume or its
blocking equivalent Process::bresume. To resume
execution of suspended processes on an application-wide basis (for all
Process objects managed by an Application object), the
analysis tool can use the Application::resume or
Application::bresume functions.

Note that the process must be attached in order for the analysis tool to
resume its execution. In other words, the Process object
must be in the PRC_attached state; the analysis tool can query
a Process object's state by calling the
Process::query_state function.

For more information on the Process::resume,
Process::bresume,
Application::resume, or
Application::bresume functions, refer to their UNIX man
pages, or their entries in the DPCL Class Reference

To suspend execution of a single process, the analysis tool can use the
asynchronous function Process::suspend or its blocking
equivalent Process::bsuspend. To suspend
execution of processes on an application-wide basis (for all
Process objects managed by an Application object), the
analysis tool can use the Application::suspend or
Application::bsuspend functions.

Note that the process must be attached in order for the analysis tool to
suspend its execution. In other words, the Process object
must be in the PRC_attached state; the analysis tool can query
a Process object's state by calling the
Process::query_state function.

For more information on the Process::suspend,
Process::bsuspend,
Application::suspend, and
Application::bsuspend functions, refer to their UNIX
man pages or their entries in the DPCL Class Reference

When attached to a target application process (in other words, when the
Process is in the PRC_attached state), the analysis tool
can terminate execution of the process. The analysis tool can also
terminate a process if it has created the process (in other words, when the
Process is in the PRC_created state). If it has
created the process, the analysis tool does not need to attach to it in order
to terminate its execution. If the analysis tool has, on the other
hand, merely connected to a running process, it must attach to the process in
order to terminate it. To determine if a process is in one of the
required states (PRC_created or PRC_attached), the
analysis tool can query its state by calling the
Process::query_state function. To terminate a
single target application process, the analysis tool can use the asynchronous
function Process::destroy or its blocking equivalent
Process::bdestroy. To terminate processes on an
application-wide basis (for all Process objects managed by an
Application object), the analysis tool can use the functions
Application::destroy or
Application::bdestroy. When using any of these
functions, however, the analysis tool should exercise the same caution it
would use when calling the UNIX command kill. Killing
selected processes in a message-passing parallel program, for example, could
result in program deadlock among the remaining processes.

Destroying a one or more processes as shown in the preceding table places
the Process object(s) in a destroyed state. This state is
represented by the enumeration constant PRC_destroyed of the
Process class' ConnectState enumeration
type. The analysis tool can query a Process object's
state by calling the Process::query_state
function.

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

An analysis tool does not need to explicitly detach itself from the target
application process. When either the analysis tool process or the
target application process terminates, the attachment will, or course, be
broken. However, it is also important to note that only one analysis
tool can be attached to a particular process at a time. For this
reason, an analysis tool may want to detach itself from the process when it no
longer needs to control execution of the process. This enables another
analysis tool to attach to the process.

To detach itself from a single process, the analysis tool can use the
asynchronous function Process::detach or its blocking
equivalent Process::bdetach. To detach itself
from processes on an application-wide basis (for all Process
objects managed by an Application object), the analysis tool can
use the functions Application::detach or
Application::bdetach. Naturally the process must
be attached in order for the analysis tool to detach it. In other
words, the Process object must be in the PRC_attached
state; the analysis tool can query a Process object's
state by calling the Process::query_state
function.

For more information on the Process::detach,
Process::bdetach,
Application::detach, and
Application::bdetach functions, refer to their UNIX man
pages or their entries in the DPCL Class Reference

Note that detaching from a target application process does not remove the
analysis tool's connection to the process. The analysis tool will
still be able to install and execute probes within the process.

The following example illustrates how a target application can control
execution of target application processes. Specifically, it illustrates
the use of the Application::bsuspend,
Application::bresume,
Application::bdetach, and
Application::bdestroy calls. The user passes
this analysis tool the host name and process IDs of the target application
processes. The analysis tool:

connects and attaches to the processes. Attaching to the processes
suspends their execution.

Once execution of the processes resumes, the installed point probes collect
information until the user presses a key on the keyboard. The target
application then:

suspends execution of the target application processes,

removes the point probes, and

if the program was compiled with the flag -DLET_RUN, detaches
and disconnects from the target application processes. If the program
was not compiled with -DLET_RUN, the analysis tool terminates the
target application processes.