Objects of the Process class represent a target application process. Member functions of this class enable an analysis tool to:
Description
This enumeration type is used to describe the state of DPCL processes. The state of a process governs the actions that you can perform. For an explanation of the DPCL process states, see DPCL Programming Guide.
The following are members of the enumerated type of
ConnectState.
Table 14. ConnectState Enumeration Types
| Enumeration Type | Description |
|---|---|
| PRC_attached | PRC_connected, plus can issue process control functions |
| PRC_connected | Tool is connected to the target application which can be instrumented |
| PRC_created | The target application has been created and is suspended |
| PRC_destroyed | Target application has been destroyed |
| PRC_pre_create | Process constructor has been called in preparation for the create call |
| PRC_unconnected | Process constructor has been called in preparation for the connect call |
| PRC_unknown_state | Current state is unknown |
Synopsis
#include <Process.h>
Process(void);
Process(const Process ©);
Process(
const char *host_name,
int task_pid,
int task_num = 0);
Parameters
Description
The default constructor creates a Process object in an unused state. Specifically, the task number and process ID are both -1, and the host name is 0.
The copy constructor uses the values contained in the copy argument to initialize the new (constructed) object. No attempt is made to connect to the process represented by the copy argument, whether or not it is already connected.
The standard constructor uses the arguments provided to initialize the object. No attempt is made to connect to the process. task_num is a value that is used only by queries on the client and does not affect the connection in any way.
Exceptions
See Also
bconnect, bdisconnect, connect, disconnect, remove_process
Synopsis
#include <Process.h>
AisStatus activate_probe(
short count,
ProbeHandle *phandle,
GCBFuncType ack_cb_fp,
GCBTagType ack_cb_tag);
Parameters
Description
Activates a list of probes that have been installed within a process. The activation is atomic in the sense that all probes are activated or all probes fail to be activated for the process.
phandle is an input array generated by an install_probe or binstall_probe call. It is supplied by the caller and must contain at least count elements. The ith element of the array is a handle, or identifier, that identifies the ith probe expression.
To activate a set of probes, the process must be in a connected, created, or attached state, and the probes must have been previously installed in that process.
Note that the function submits the request to activate the probes and returns immediately. If the return value has an AisSeverityCode of ASC_error or worse, the function returns immediately and the user-specified callback will not be invoked.The acknowledgement callback function receives notification of the success or failure of the activation.
Return Values
The return value indicates whether the request for activation was successfully submitted, but indicates nothing about whether the request itself was successfully executed.
Callback Data
When no callback function is provided (when a value of NULL is used as the value for the callback function), the operation is still executed, but no callback is called.
The callback function is invoked once for each process for which a probe activation is requested. When the callback is invoked, the callback function is passed a pointer to the process as the callback object. The callback message is the request status, of type AisStatus*, which contains one of the following status values:
See Also
bactivate_probe, bconnect, bdeactivate_probe, bdisconnect, binstall_probe, class Process, connect, deactivate_probe, disconnect, GCBFuncType, install_probe
Synopsis
#include <Process.h>
AisStatus add_phase(
const Phase &ps,
GCBFuncType ack_cb_fp,
GCBTagType ack_cb_tag);
AisStatus add_phase(
const Phase &ps,
ProbeExp init_func,
GCBFuncType init_cb_fp,
GCBTagType init_cb_tag,
GCBFuncType ack_cb_fp,
GCBTagType ack_cb_tag);
Parameters
Description
Adds a new phase structure to the process. A process must be connected in order to add a new phase. The phase does not execute for the first time until the amount of time indicated by the phase period has elapsed, starting from the time the phase is added to the process.
The return value indicates whether the request to add the phase was submitted successfully, but indicates nothing about whether the request itself was successfully executed. If the return value has an AisSeverityCode of ASC_error or worse, the function returns immediately and the user-specified callback will not be invoked.
The initialization function must be signal-safe, and must be loaded into the application (using a probe module) before this operation may take place. The function prototype for the initialization function is:
void init_func(void * msg_handle);
To use Ais_send in this initialization function:
int size;
char * str;
Ais_send (msg_handle, str, size);
Return Values
Callback Data
When no callback function is provided, (when a value of NULL is used as the value for the callback function), the operation is still executed, but no callback is called.
The init_cb_fp callback function is invoked each time the corresponding function in the process instrumentation, init_func, sends a message to the client. The message format is determined by the function that sends the message.
The ack_cb_fp callback function is invoked once for each process for which a phase addition is requested. When the callback is invoked, the callback function is passed a pointer to the process as the callback object. Specify the function name or NULL.
The callback message is the request status, of type AisStatus*, which contains one of the following status values:
See Also
alloc_mem, badd_phase, bconnect, bdisconnect, class GenCallBack, class ProbeModule, class Process, connect, disconnect, GCBFuncType, GCBTagType, free_mem.
Synopsis
#include <Process.h>
ProbeExp alloc_mem(
ProbeType pt,
void *init_val,
GCBFuncType ack_cb_fp,
GCBTagType ack_cb_tag,
AisStatus &stat);
ProbeExp alloc_mem(
ProbeType pt,
void *init_val,
const Phase &ps,
GCBFuncType ack_cb_fp,
GCBTagType ack_cb_tag,
AisStatus &stat);
Parameters
Description
Allocates a block of probe data in a process. It returns a single probe expression that may be used to reference the allocated data. The data may be referenced in a probe expression that may be installed in the process.
The second form of alloc_mem is used with phases and can be called only after the corresponding phase object has been installed by the add_phase or badd_phase call.
Note that alloc_mem returns control to the caller immediately and does not wait until it has either succeeded or failed on the process. If the return value has an AisSeverityCode of ASC_error or worse, the function returns immediately and the user-specified callback will not be invoked. The probe expression that represents the allocation is returned immediately whether or not the allocation succeeds. The returned probe expression may be used as a data reference on the process if the allocation succeeds. If the data reference is used in another probe expression, and the client attempts to install that probe expression in a process in which the allocation failed, that probe expression will fail to install. Similarly, if you attempt to install the probe in a process in which the data was not allocated, the installation will fail.
stat indicates whether the request for allocation was submitted successfully. If the request was submitted successfully, stat is given the value ASC_success. If a request cannot be submitted, stat is given the value ASC_operation_failed.
Return Values
Returns a probe expression that may be used as a valid reference to the data on this process, if the data has been allocated successfully.
Callback Data
When no callback function is provided (when a value of NULL is used as the value for the callback function), the operation is still executed but no callback is called.
The callback function is invoked once, when the acknowledgement message is received, and then removed. When the callback is invoked the callback function is passed a pointer to the process as the callback object. The callback message is the request status, of type AisStatus*, which contains one of the following status values:
See Also
add_phase, balloc_mem, bfree_mem,free_mem
Synopsis
#include <Process.h>
AisStatus attach(
GCBFuncType fp,
GCBTagType tag);
Parameters
Description
Attaches to this process. When connecting multiple DPCL clients to a process or application, only one client can be attached at a time. Attaching to a process allows the tool to control the execution directly, such as resuming and suspending execution. Processes must first be connected or created before they can be attached.
This function not only attaches to the process, but also suspends its execution in the same way that a call to the suspend or bsuspend function would. To resume execution of the process, the analysis tool can call the resume or bresume function.
Note that the function submits the request to attach to a process and returns immediately. The callback function receives notification of whether the attachment was successful or if it failed.
Return Values
The return value for attach indicates whether the request was submitted successfully, but does not indicate whether the request itself executed successfully.
Callback Data
When no callback function is provided (when a value of NULL is used as the value for the callback function), the operation is still executed, but no callback is called.
The callback function is invoked once for each process for which an attach is requested. When the callback is invoked, the callback function is passed a pointer to the process as the callback object. The callback message is the request status, of type AisStatus*, which contains one of the following status values:
See Also
battach, bdetach, detach
Synopsis
#include <Process.h>
AisStatus bactivate_probe(
short count,
ProbeHandle *phandle);
Parameters
Description
Activates a list of probes that have been installed within a process. The activation is atomic in the sense that all probes are either activated, or all probes fail to be activated, for any given process.
phandle is an input array generated by an install_probe or binstall_probe call. It is supplied by the caller and must contain at least count elements. The ith element of the array is a handle, or identifier, that identifies the ith probe expression.
To activate a set of probes, the process must be in a connected, created, or attached state, and the probes must have been previously installed in the process.
Note that the function submits the request to activate the probes and waits until the request has completed.
Return Values
The return value indicates whether the request for activation was successfully executed.
See Also
activate_probe, bconnect, bdeactivate_probe, bdisconnect, binstall_probe, connect, deactivate_probe, disconnect, install_probe.
Synopsis
#include <Process.h>
AisStatus badd_phase(const Phase &ps);
AisStatus badd_phase(
const Phase &ps,
ProbeExp init_func,
GCBFuncType init_cb_fp,
GCBTagType init_cb_tag);
Parameters
Description
Adds a new phase structure to a connected process. A process must be connected in order to add a new phase. The phase does not execute for the first time until the amount of time indicated by the phase period has elapsed, starting from the time the phase is added to the process.
Note that the function submits a request to add the phase and waits until the request has completed. The return value indicates whether the request was successfully executed.
The initialization function must be signal-safe, and must be loaded into the application (using a probe module) before this operation can take place. The function prototype for the initialization function is:
void init_func(void * msg_handle);
To use Ais_send in this initialization function:
int size;
char * str;
Ais_send (msg_handle, str, size);
Return Values
The return value indicates whether the request to add the phase was executed successfully.
Callback Data
When no callback function is provided (when a value of 0 is used as the value for the callback function), the operation is still executed, but no callback is called.
The callback function is invoked each time the corresponding function in the process instrumentation, init_func, sends a message to the client. The message format is determined by the function that sends the message.
See Also
add_phase, alloc_mem, bconnect, bdisconnect, class ProbeModule, connect, disconnect, free_mem
Synopsis
#include <Process.h>
ProbeExp balloc_mem(
ProbeType pt,
void *init_val,
AisStatus &stat);
ProbeExp balloc_mem(
ProbeType pt,
void *init_val,
const Phase &ps,
AisStatus &stat);
Parameters
Description
Allocates a block of probe data in a process. It returns a single probe expression that may be used to reference the allocated data. The data may be referenced in a probe expression that may be installed in the process.
If the block of probe data is used by a Phase object, balloc_mem can be called only after the corresponding phase object has been installed by the add_phase or badd_phase call.
Note that balloc_mem does not return control to the caller until it has either succeeded or failed on the process. If the allocation succeeds, it returns a valid probe expression data reference and stat is given the value ASC_success. If the allocation fails, then stat is given the value ASC_operation_failed, and any probe that references the returned value of balloc_mem fails to install.
Return Values
Returns a probe expression that may be used as a valid reference to the data on this process.
See Also
add_phase, alloc_mem, badd_phase, bfree_mem, free_mem
Synopsis
#include <Process.h> AisStatus battach(void);
Description
Attaches to a process. When connecting multiple DPCL clients to a process or application, only one client can be attached at a time. Attaching to a process or application allows the tool to control the execution directly, such as resuming and suspending the process. Processes must first be connected or created before they can be attached.
This function not only attaches to the process, but also suspends its execution in the same way that a call to the suspend or bsuspend function would. To resume execution of the process, the analysis tool can call the resume or bresume function.
Note that battach does not return control to the caller until the attachment has either succeeded or failed. The return value indicates whether the attachment succeeded or failed.
Return Values
The return value for battach indicates whether the attachment was successfully established.
See Also
attach, bdetach, detach
Synopsis
#include <Process.h> AisStatus bconnect(void);
Description
Connects a DPCL client to a process. Connection to a process establishes a communication channel to the host where the process resides and creates the environment within that process that allows the client to insert and remove instrumentation, etc.
Connections from multiple DPCL based tools to the same process are allowed.
Note that bconnect does not return control to the caller until the connection has either succeeded or failed. The return value indicates whether the connection succeeded or failed.
Return Values
The return value for bconnect indicates whether the connection was established successfully.
See Also
bdisconnect, connect, disconnect
Synopsis
#include <Process.h> AisStatus bcreate( const char *host, const char *path, const char *const argv[], const char *const envp[], char *remote_stdin_filename, char *remote_stdout_filename, char *remote_stderr_filename, GCBFuncType stdout_cb_fp, GCBTagType stdout_cb_tag, GCBFuncType stderr_cb_fp, GCBTagType stderr_cb_tag); AisStatus bcreate( const char *host, const char *path, const char *const argv[], const char *const envp[], GCBFuncType stdout_cb_fp, GCBTagType stdout_cb_tag, GCBFuncType stderr_cb_fp, GCBTagType stderr_cb_tag); AisStatus bcreate( const char *host, const char *path, const char *const argv[], const char *const envp[], char *remote_stdin_filename, char *remote_stdout_filename, char *remote_stderr_filename);
Parameters
Description
Creates a process on the specified host. The process is created in a stopped state, and a connection is established that allows the client to insert instrumentation into the created process. The current working directory for the process is $HOME. The process must be started to begin execution.
The input file name, output file names, output callbacks and PoeAppl::send_stdin can be used to send the stdio to and from the process.
If you pass callback functions as stdout_cb_fp and stderr_cb_fp parameters, the output from the process will be available in these callbacks. Input to the process can be sent using send_stdin().
Another way to send stdio to and from the process is to specify the remote file name parameters. In this case stdin, stdout and stderr can be set to use files on the host where the process is running. The file specified by the remote_stdin_filename parameter must already exist. The files for the remote_stdout_filename and remote_stderr_filename will be created or overwritten if they already exist. If one of the remote file parameters is specified, it takes precedence over the corresponding callback or send_stdin() method of handling stdio.
Note that bcreate does not return control to the caller until the new process has been created or has failed to be created. The return value indicates whether the operation succeeded or failed.
Return Values
The return value for bcreate indicates whether the process was created successfully.
Callback Data
The stdout_cb_fp callback function is invoked each time the process sends data to stdout.
The stderr_cb_fp callback function is invoked each time the process sends data to stderr.
The output will be contained in the message parameter of the callback. The size of the output will be contained in the msg_size field of the sys callback parameter. The output from the process may be received in different size blocks than were actually sent by the program.
See Also
bdestroy, bstart, create, destroy, send_stdin, start
Synopsis
#include <Process.h>
AisStatus bdeactivate_probe(
short count,
ProbeHandle *phandle);
Parameters
Description
Accepts an array of probe handles as an input parameter. Each probe handle in the array represents a probe that has been installed in the application. The client sends a request to the process within the application to deactivate the list of probes represented by the array. Probes are deactivated atomically for the process in the sense that the process is temporarily stopped, all probes on the list are deactivated, then the process is resumed.
phandle is an input array generated by an install_probe or binstall_probe call. It is supplied by the caller and must contain at least count elements. The ith element of the array is a handle, or identifier, that identifies the ith probe expression.
Note that bdeactivate_probe does not return control to the caller until all probes in the array have been deactivated on the process. The return value indicates whether all probes in the list were deactivated or one or more probes were left intact.
Return Values
The return value for bdeactivate_probe indicates whether the deactivations were successfully completed.
See Also
activate_probe, deactivate_probe
Synopsis
#include <Process.h> AisStatus bdestroy(void);
Description
Destroys or terminates the process. In general, a process must first be attached in order for it to be destroyed. If a process has just been created, and is in PRC_created_state, it may be destroyed without attaching.
After issuing bdestroy, any SourceObj object that is associated with this Process object should not be used, relative to this process.
Note that bdestroy does not return control to the caller until the process has been destroyed or has failed to be destroyed.
The return value indicates whether the termination succeeded or failed.
Return Values
The return value for bdestroy indicates whether the termination successfully completed.
See Also
attach, battach, destroy
Synopsis
#include <Process.h> AisStatus bdetach(void);
Description
Detaches the process. Process control flow, such as suspending and resuming the process, can only be done while a process is in an attached state. Detaching a process removes the level of process control available to the client or tool when the process is attached, but retains the process connection so probe installation, activation, removal, and so forth, can still take place.
Note that bdetach does not return control to the caller until the process has detached or has failed to do so. The return value indicates whether the process successfully detached or failed to detach.
Return Values
The return value for bdetach indicates whether the process detached successfully.
See Also
attach, battach, detach
Synopsis
#include <Process.h> AisStatus bdisconnect(void);
Description
Disconnects from the process. Disconnecting from an application process removes the application environment created by a connection. All instrumentation and data are removed from the application process.
After issuing bdisconnect, any SourceObj object that is associated with this Process object should not be used, relative to this process.
Note that bdisconnect does not return control to the caller until the process has either succeeded or failed to disconnect.
Return Values
The return value for bdisconnect indicates whether the connection was successfully terminated.
See Also
bconnect, connect, disconnect
Synopsis
#include <Process.h>
AisStatus bexecute(
ProbeExp pexp,
GCBFuncType data_cb_fp,
GCBTagType data_cb_tag);
Parameters
Description
Executes a probe expression within the application process. The expression is executed once, then removed. The application process is interrupted, the expression is executed, then the process is returned to its previous execution state.
Note that bexecute does not return control to the caller until the probe expression has either succeeded or failed to execute.
Note that one-shot probes must be signal-safe. Refer to the sigaction (UNIX) manual page for a list of the UNIX functions that are signal-safe.
Return Values
The return value for bexecute indicates whether the request for execution succeeded or failed.
Callback Data
When no callback function is provided (when a value of NULL is used as the value for the callback function), the operation is still executed, but no callback is called. The callback function is invoked once for each message sent from the probe. When the callback is invoked the callback function is passed a pointer to the process as the callback object. The callback tag is given in the data_cb_tag variable. The callback message is the data sent by the probe using the Ais_send() function call.
See Also
Ais_send, execute
Synopsis
#include <Process.h> AisStatus bfree_mem(ProbeExp pexp);
Parameters
Description
Deallocates a block of dynamically allocated probe memory in an application process. The probe expression must contain only a single reference to a block of data allocated by the alloc_mem or balloc_mem functions.
Note that bfree does not return control to the caller until deallocating the block of memory has either succeeded or failed.
Return Values
The return value for bfree_mem indicates whether the requests for deallocation were successfully executed.
See Also
balloc_mem, bfree_mem, free_mem
Synopsis
#include <Process.h>
AisStatus binstall_probe(
short count,
ProbeExp *probe_exp,
InstPoint *point,
GCBFuncType *data_cb_fp,
GCBTagType *data_cb_tag,
ProbeHandle *phandle);
Parameters
Description
Installs probe expressions as instrumentation at specific locations within the process. Probe expressions are installed atomically in the sense that, within a process, either all probe expressions in the request are installed in the process, or none are installed. The return value indicates whether all probes were installed, or whether the process was unable to install the expressions.
data_cb_fp is an input array supplied by the caller that must contain at least count elements. The ith element of the array is a pointer to a callback function that is invoked each time the ith probe in phandle sends data via the AisSendMsg function. data_cb_tag is a similar array that contains the callback tag used when callbacks in data_cb_fp are invoked. The ith callback tag is used with the ith callback.
phandle is an output array supplied by the caller that must contain at least count elements. The ith element of the array is a handle, or identifier, to be used in subsequent references to the ith probe expression. For example, it is needed when the client activates, deactivates or removes a probe expression from an application or process. phandle does not contain valid information if the installation fails.
Note that binstall_probe does not return control to the caller until all probe expressions have been installed or failed to install within the process.
Return Values
The return value for binstall_probe indicates whether the probe installations were successful.
Callback Data
When no callback function is provided (when a value of NULL is used as the value for the callback function), the operation is still executed, but no callback is called.
The callback function is invoked once for each message sent from the probe. When the callback is invoked the callback function is passed a pointer to the process as the callback object. The callback tag is given in the data_cb_tag array. The callback message is the data sent by the probe using the Ais_send function call.
See Also
Ais_send, install_probe
Synopsis
#include <Process.h> AisStatus bload_module(ProbeModule *module);
Parameters
Description
Sends and loads the module from the client side to the user application. Once loaded, the probe expressions available in this probe module can be installed and activated as if they are native in the application.
Note that bload_module does not return control to the caller until the probe module has either installed, or has failed to install in the process.
Each subsequent call to this function, with the same module specified, loads another copy of the module.
Exceptions
Return Values
The return value for bload_module indicates whether the probe module installation was successful.
See Also
bunload_module, load_module, ProbeModule::get_reference,unload_module
Synopsis
#include <Process.h> AisStatus bremove_phase(const Phase &ps);
Parameters
Description
Removes a phase from the application. Data and functions associated with the phase are unaffected by removing the phase. Existing probe data cannot be associated with a phase except at the time that the data was allocated. As a result, deleting one phase permanently disassociates data from any other phase.
bremove_phase can be called only after the corresponding phase object has been installed by the add_phase or badd_phase call.
Note that bremove_phase does not return control to the caller until the phase has been removed or has failed to be removed from the process.
Return Values
The return value for bremove_phase indicates whether the phase was removed successfully from the process.
See Also
add_phase, badd_phase, bset_phase_exit, bset_phase_period, get_phase_period, remove_phase, set_phase_exit, set_phase_period
Synopsis
#include <Process.h>
AisStatus bremove_probe(
short count,
ProbeHandle *phandle);
Parameters
Description
Deletes or removes probe expressions that have been installed in a process. If all probe expressions are installed and deactivated, the probe expressions are removed and a normal return status results. If one or more of the probe expressions are currently active, the expressions are deactivated and removed, and the return status indicates there were active probes at the time of their removal. If one or more of the probes do not exist, all existing probes are removed and the return status indicates an appropriate warning. If one or more of the probe expressions exists but cannot be removed, an error results and none of the probe expressions is removed. If the process is not connected a warning is returned.
phandle is an input array generated by an install_probe or binstall_probe call. It is supplied by the caller and must contain at least count elements. The ith element of the array is a handle, or identifier, that identifies the ith probe expression.
Probe expression removal is atomic in the sense that either all probe expressions are removed from a given process or none are removed. When probes are removed from a process, the process is temporarily stopped, all indicated probes are removed, and the process is resumed.
Note that bremove_probe does not return control to the caller until the probes have been removed or have failed to be removed from the process. If one or more probes cannot be removed for any reason, as many probes as possible are removed, and status indicates the condition.
Return Values
The return value for bremove_probe indicates whether all probes in the list were successfully removed from the process.
See Also
activate_probe, bactivate_probe, bdeactivate_probe, binstall_probe, deactivate_probe, install_probe, remove_probe
Synopsis
#include <Process.h> AisStatus bresume(void);
Description
Resumes execution of a process that has been temporarily suspended by a suspend or bsuspend function call. A process must be attached in order for it to be resumed. Calling this function with a process object that is not attached or suspended will result in an error return value.
Note that bresume does not return control to the caller until the process has resumed or has failed to resume.
Return Values
The return value for bresume indicates whether the process was successfully resumed.
See Also
attach, battach, bconnect, bdetach, bdisconnect, bsuspend, connect, detach, disconnect, resume, suspend
Synopsis
#include <Process.h>
AisStatus bset_phase_exit(
const Phase &ps,
ProbeExp begin_func,
GCBFuncType begin_cb_fp,
GCBTagType begin_cb_tag,
ProbeExp data_func,
GCBFuncType data_cb_fp,
GCBTagType data_cb_tag,
ProbeExp end_func,
GCBFuncType end_cb_fp,
GCBTagType end_cb_tag);
Parameters
Description
Specifies a set of exit functions to be executed when any of the following three events occur.
bset_phase_exit can be called only after the corresponding phase object has been installed by the add_phase or badd_phase call.
Note that bset_phase_exit immediately returns control to the caller upon submitting the request to the daemon. It does not wait until the exit functions have been placed in the indicated phase, or the operation failed to complete.
Each of the phase functions must be signal-safe, and must be loaded into the application before this operation may take place. The function prototypes for the functions are:
void begin_func(void *msg_handle); void data_func(void *msg_handle, void *data); void end_func(void *msg_handle);
Return Values
The return value for bset_phase_exit indicates whether the request to set exit functions for the indicated phase on the process was successfully submitted. It gives no indication of whether the request was successfully executed.
Callback Data
When no callback function is provided (when a value of NULL is used as the value for the callback function, the operation is still executed but no callback is called.
The following callback functions are invoked each time the corresponding function in the process instrumentation (begin_func, data_func, or end_func) sends a message to the client.
The message format is determined by the function that sends the message.
See Also
add_phase, badd_phase, bremove_phase, bset_phase_period, get_phase_period, remove_phase, set_phase_exit, set_phase_period
Synopsis
#include <Process.h>
AisStatus bset_phase_period(
const Phase &ps,
float period);
Parameters
Description
Changes the time interval between successive activations of a phase within the process. Processes which do not have the phase installed result in an informational return code. Processes that are not connected result in a warning return code.
The new period is represented by a positive floating-point value. If the value is smaller than the minimum activation time interval allowed by the setitimer system call, the minimum activation time interval will be used. After the new period is set, the phase will be activated when the new period expires.
bset_phase_period can be called only after the corresponding phase object has been installed by the badd_phase call.
Note that bset_phase_period does not return control to the caller until the phase period has been set or has failed to be set in the process.
Return Values
The return value for bset_phase_period indicates whether the phase period was set successfully on this process.
See Also
add_phase, badd_phase, bremove_phase, get_phase_period, remove_phase, set_phase_period
Synopsis
#include <Process.h> AisStatus bstart(void);
Description
Starts the execution of a process that has been created but has not yet begun executing. To get a created process running, you must issue one start. Subsequent starts cannot be issued.
Note that bstart does not return control to the caller until the process has either started or has failed to start.
Return Values
The return value for bstart indicates whether the process was started successfully.
See Also
bcreate, bdestroy, create, destroy, start
Synopsis
#include <Process.h> AisStatus bsuspend(void);
Description
Suspends a process that is executing. A tool must be attached to a process in order to suspend process execution.
Note that bsuspend does not return control to the caller until the process has either been suspended or has failed to be suspended.
Return Values
The return value for bsuspend indicates whether all processes within the application were suspended successfully.
See Also
attach, battach, bresume, resume, suspend
Synopsis
#include <Process.h> AisStatus bunload_module(ProbeModule* module);
Parameters
Description
Unloads the module from the process. Once unloaded, all the probe handles that refer to this probe module are automatically removed.
Note that bunload_module does not return control to the caller until the probe module has either been removed, or has failed to be removed, from the application process.
Return Values
The return value for bunload_module indicates whether the probe module was removed successfully from the process.
See Also
bload_module, load_module, unload_module
Synopsis
#include <Process.h>
AisStatus connect(
GCBFuncType fp,
GCBTagType tag);
Parameters
Description
Connection to a process established a communication channel to the host on which the process resides (the host), and creates the environment within that process that allows the client to insert and remove instrumentation, alter its control flow, and so forth.
Connections from multiple DPCL analysis tools to the same process are allowed.
Note that the function submits the requests to connect the process and returns immediately. The callback function receives notification of a connection's success or failure.
Return Values
The return value for connect indicates whether the request for connection was successfully submitted, but indicates nothing about whether the request was executed successfully, but does not indicate whether the request was successfully executed.
Callback Data
When no callback function is provided (when NULL is used as the value for the callback function), the operation is still executed but no callback is called.
The callback function is invoked once for each process for which a connection is requested. When the callback is invoked, the callback function is passed a pointer to the process as the callback object. The callback message is the request status, of type AisStatus*, which contains one of the following status values:
See Also
bconnect, bdisconnect, disconnect
Synopsis
#include <Process.h> AisStatus create( const char *host, const char *path, const char *const argv[], const char *const envp[], char *remote_stdin_filename, char *remote_stdout_filename, char *remote_stderr_filename, GCBFuncType stdout_cb_fp, GCBTagType stdout_cb_tag, GCBFuncType stderr_cb_fp, GCBTagType stderr_cb_tag, GCBFuncType ack_cb_fp, GCBTagType ack_cb_tag); AisStatus create( const char *host, const char *path, const char *const argv[], const char *const envp[], GCBFuncType stdout_cb_fp, GCBTagType stdout_cb_tag, GCBFuncType stderr_cb_fp, GCBTagType stderr_cb_tag, GCBFuncType ack_cb_fp, GCBTagType ack_cb_tag); AisStatus create( const char *host, const char *path, const char *const argv[], const char *const envp[], char *remote_stdin_filename, char *remote_stdout_filename, char *remote_stderr_filename, GCBFuncType ack_cb_fp, GCBTagType ack_cb_tag);
Parameters
Description
Creates a process on the specified host. The process is created in a stopped state, and a connection is established that allows the client to insert instrumentation into the new process. The current working directory for the process is $HOME. The process must be started to begin execution.
The input file name, output file names, output callbacks and send_stdin can be used to access the stdio to and from the process.
If you pass callback functions to the stdout_cb_fp and stderr_cb_fp parameters, the output from the process will be available in these callbacks. Input to the process can be sent using send_stdin().
Another way to access stdio to the process is to specify the remote file name parameters. In this case, stdin, stdout, and stderr can be set to use files on the host on which the process is running. The file specified by the remote_stdin_filename parameter must already exist. The files for the remote_stdout_filename and remote_stderr_filename parameters are created or overwritten if they already exist. If one of the remote file parameters is specified, it takes precedence over the corresponding callback or send_stdin() method of handling stdio.
Note that create immediately returns control to the caller. It does not wait until the process has been created. If the return value has an AisSeverityCode of ASC_error or worse, the function returns immediately and the user-specified callback will not be invoked.
Return Values
The return value for create indicates whether the request to create a process was submitted successfully, but does not indicate whether the request was executed successfully.
Callback Data
When no callback function is provided (when a value of NULL is used as the value for the callback function), the operation is still executed but no callback is called.
The ack_cb_fp callback function is invoked once, when the new process is created. When the callback is invoked, the callback function is passed a pointer to the process as the callback object. Specify the function name or NULL.
The callback message is the request status, of type AisStatus*, which contains one of the following status values:
stdout_cb_fp. This callback function is invoked each time the process sends data to stdout.
stderr_cb_fp. This callback function is invoked each time the process sends data to stderr.
The output is contained in the message parameter of the callback. The size of the output will be contained in the msg_size field of the sys callback parameter. The output from the process may be received in different size blocks than were actually sent by the program.
See Also
bcreate, bdestroy, bstart, destroy, start
Synopsis
#include <Process.h>
AisStatus deactivate_probe(
short count,
ProbeHandle *phandle,
GCBFuncType ack_cb_fp,
GCBTagType ack_cb_tag);
Parameters
Description
Accepts an array of probe handles as an input parameter. Each probe handle in the array represents a probe that has been installed in the application. The client sends a request to the process within the application to deactivate the list of probes represented by the array. Probes are deactivated atomically for the process in the sense that the process is temporarily stopped, all probes on the list are deactivated, then the process is restarted.
phandle is an input array generated by an install_probe or binstall_probe call. It is supplied by the caller and must contain at least count elements. The ith element of the array is a handle, or identifier, that identifies the ith probe expression.
Note that deactivate_probe immediately returns control to the caller. It does not wait until all probes in the array have been deactivated on the application processes. If the return value has an AisSeverityCode of ASC_error or worse, the function returns immediately and the user-specified callback will not be invoked. The return value indicates whether the request was successfully submitted and gives no indication whatever about the success or failure of the execution of the request.
Return Values
The return value for deactivate_probe indicates whether the deactivations were successfully submitted.
Callback Data
When no callback function is provided (when a value of NULL is used as the value for the callback function), the operation is still executed but no callback is called.
When the callback is invoked, the callback function is passed a pointer to the process as the callback object. The callback message is the request status, of type AisStatus*, which contains one of the following status values:
See Also
activate_probe, Application::activate_probe, Application::bactivate_probe, Application::bdeactivate_probe, bactivate_probe, bdeactivate_probe
Synopsis
#include <Process.h>
AisStatus destroy(
GCBFuncType fp,
GCBTagType tag);
Parameters
Description
Destroys or terminates the target processes. A process must first be attached before it can be destroyed. If a process has just been created, and is in PRC_created_state, it may be destroyed without attaching.
After issuing bdisconnect, any SourceObj object that is associated with this Process object should not be used, relative to this process.
Note that destroy immediately returns control to the caller. It does not wait until all processes within the application have been destroyed. The return value indicates whether the request was submitted successfully, but does not indicate whether the request was executed successfully.
Return Values
The return value for destroy indicates whether the termination was requested successfully.
Callback Data
When no callback function is provided (when a value of NULL is used as the value for the callback function), the operation is still executed but no callback is called.
The callback function is invoked once, when the termination is attempted. When the callback is invoked, the callback function is passed a pointer to the process as the callback object. The callback message is the request status, of type AisStatus*, which contains one of the following status values:
See Also
attach, battach, bdestroy
Synopsis
#include <Process.h>
AisStatus detach(
GCBFuncType fp,
GCBTagType tag);
Parameters
Description
Detaches from this process. Process control flow, such as suspending and resuming a process, can only be done while a process is in an attached state. Detaching a process removes the level of process control available to the tool when the process is attached. However, when a process is detached, the process connection is retained so probes can still be installed, activated, removed, and so forth.
Note that detach immediately returns control to the caller upon issuing a request to detach from a process. The return value indicates whether the request was submitted submitted.
Return Values
The return value for detach indicates whether the request was successfully submitted.
Callback Data
When no callback function is provided (when a value of NULL is used as the value for the callback function), the operation is still executed but no callback is called.
When the callback is invoked, the callback function is passed a pointer to the process as the callback object. The callback message is the request status, of type AisStatus*, which contains one of the following status values:
See Also
attach, battach, bdetach
Synopsis
#include <Process.h>
AisStatus disconnect(
GCBFuncType fp,
GCBTagType tag);
Parameters
Description
Disconnecting from an application process removes the application environment created by a connection. All instrumentation and data are removed from the application process.
After issuing bdisconnect, any SourceObj object that is associated with this Process object should not be used, relative to this process.
Note that the function submits the request to disconnect the process and returns immediately. The callback function receives notification of a disconnection's success or failure.
Return Values
The return value for disconnect indicates whether the request for disconnection was successfully submitted, but indicates nothing about whether the request was successfully executed.
Callback Data
When no callback function is provided (when a value of NULL is used as the value for the callback function), the operation is still executed but no callback is called.
The callback function is invoked once, when the process is (or fails to be) disconnected. When the callback is invoked, the callback function is passed a pointer to the process as the callback object. The callback message is the request status, of type AisStatus*, which contains one of the following status values:
See Also
bconnect, bdisconnect, connect
Synopsis
#include <Process.h>
AisStatus execute(
ProbeExp probe_exp,
GCBFuncType data_cb_fp,
GCBTagType data_cb_tag,
GCBFuncType ack_cb_fp,
GCBTagType ack_cb_tag);
Parameters
Description
Executes a probe expression within the application process. The expression is executed once, then removed. The application process is interrupted, the expression is executed, then the process is returned to its previous execution state.
Note that execute immediately returns control to the caller upon submitting its request to the daemon. It does not wait until the probe expression has executed or has failed to execute. If the return value has an AisSeverityCode of ASC_error or worse, the function returns immediately and the user-specified callback will not be invoked. The acknowledgement callback function receives notification of the success or failure of the execution.
Note that one-shot probes must be signal-safe. Refer to the sigaction (UNIX) manual page for a list of the UNIX functions that are signal-safe.
Return Values
The return value for execute indicates whether the request for deallocation was successfully submitted, but does not indicate whether the request was executed successfully.
Callback Data
When no callback function is provided (when a value of NULL is used as the value for the callback function), the operation is still executed but no callback is called.
The data_cb_fp callback function is invoked once for each message sent from the probe. When the callback is invoked, the callback function is passed a pointer to the process as the callback object. The callback tag is given in the data_cb_tag array. The callback message is the data sent by the probe using the Ais_send() function call.
The ack_cb_fp callback function is invoked once, when execution succeeds or fails. When the callback is invoked, the callback function is passed a pointer to the process as the callback object. Specify the function name or NULL.
The callback message is the request status, of type AisStatus*, which contains one of the following status values:
See Also
Ais_send, bexecute
Synopsis
#include <Process.h>
AisStatus free_mem(
ProbeExp pexp,
GCBFuncType ack_cb_fp,
GCBTagType ack_cb_tag);
Parameters
Description
Deallocates a block of dynamically allocated probe memory for this process. The probe expression must contain only a single reference to a block of data allocated by the alloc_mem or balloc_mem functions.
Note that free_mem immediately returns control to the caller upon submitting its request to free the data. It does not wait until the data has either been deallocated or has failed to deallocate. If the return value has an AisSeverityCode of ASC_error or worse, the function returns immediately and the user-specified callback will not be invoked. The acknowledgement callback function receives notification of the success or failure of the deallocation.
Return Values
The return value for free_mem indicates whether the request for deallocation was submitted successfully, but indicate whether the request was executed successfully.
Callback Data
When no callback function is provided (when a value of NULL is used as the value for the callback function), the operation is still executed but no callback is called.
The callback function is invoked once when deallocation succeeds or fails. When the callback is invoked, the callback function is passed a pointer to the process as the callback object. The callback message is the request status, of type AisStatus*, which contains one of the following status values:
See Also
alloc_mem, balloc_mem, bfree_mem
Synopsis
#include <Process.h>
char *get_host_name(
char *buffer,
unsigned int len) const;
Parameters
Description
Copies into buffer a null-terminated character string that represents the name of the host processor for the indicated process. The name may be truncated if the len parameter is smaller than the length of the host name.
Return Values
Returns a pointer to buffer, which contains, at most, len bytes of the UNIX host processor name, or NULL if there is no host name associated with the process. If there is no host name associated with the Process object, the value NULL is returned.
See Also
get_host_name_length
Synopsis
#include <Process.h> unsigned int get_host_name_length(void) const;
Description
Returns the length, including the null-terminating byte, of the name of the host machine for the indicated process. If there is no host name associated with the process, then 0 is returned.
Return Values
Returns the length of the UNIX host processor name.
See Also
get_host_name
Synopsis
#include <Process.h>
float get_phase_period(
const Phase &ps,
AisStatus &stat) const;
Parameters
Description
Returns the time duration, in seconds, between successive activations of this phase. If the return value is greater than 0, the value represents the minimum time between successive activations of the phase. Due to scheduling conflicts with other processes and resources on the system, the actual time between phase activations may be greater than the stated value. If the return value is 0, it represents the fastest rate of phase activation possible. If the return value is less than 0, it indicates an error.
get_phase_period can be called only after the corresponding phase object has been installed by the add_phase or badd_phase call.
stat indicates whether the query was successful. To be successful, the process must be connected and the phase must exist on the process.
Return Values
Returns the minimum time duration, in seconds (of CPU time), between successive activations of this phase. If there is no process ID associated with the process, a -1 is returned.
See Also
add_phase, set_phase_period
Synopsis
#include <Process.h> int get_pid(void) const;
Description
Returns the UNIX process identification (pid) number for the indicated process.
Return Values
Returns the UNIX process ID
Synopsis
#include <Process.h> SourceObj get_program_object(void) const;
Description
Retrieves the top-level source object from the process. Source objects are a coarse source-level view of the program structure. Program objects represent the top level of a tree structure. Below a program object are modules, then data and functions. If the process is not connected, or some other error occurs, the source object returned will be invalid. The source object may be queried with SourceObj::src_type to determine its validity.
Return Values
Returns the program object for this process.
See Also
class SourceObj
Synopsis
#include <Process.h> int get_task(void) const;
Description
Returns the task identifier associated with this process. If if is not specified in the constructor, this value is set to -1.
Return Values
Returns the task ID for this process.
Synopsis
#include <Process.h>
AisStatus install_probe(
short count,
ProbeExp *probe_exp,
InstPoint *point,
GCBFuncType *data_cb_fp,
GCBTagType *data_cb_tag,
GCBFuncType ack_cb_fp,
GCBTagType ack_cb_tag,
ProbeHandle *phandle);
Parameters
Description
Installs probe expressions as instrumentation at specific locations within a process. Probe expressions are installed atomically in the sense that, within each process, either all probe expressions in the request are installed in the process, or none are installed. The return value indicates whether the request to install probes was submitted successfully.
phandle is an output array, supplied by the caller, that must contain at least count elements. The ith element of the array is a handle, or identifier, to be used in subsequent references to the ith probe expression. For example, it is needed when the client activates, deactivates, or removes a probe expression from an application or process. phandle does not contain valid information if the installation fails.
Note that install_probe immediately returns control to the caller upon submitting all requests to the daemons. It does not wait until all probe expressions have either been installed or have failed to be installed within all processes in the application. If the return value has an AisSeverityCode of ASC_error or worse, the function returns immediately and the user-specified callback will not be invoked.
Return Values
The return value for install_probe indicates whether the request to install probes was submitted successfully. It does not indicate whether the request was executed successfully.
Callback Data
When no callback function is provided (when a value of NULL is used as the value for the callback function), the operation is still executed but no callback is called.
The ack_cb_fp callback function is invoked once and removed. It is called when the status message for this request is received. When the callback is invoked, the callback function is passed a pointer to the process as the callback object. Specify the function name or NULL.
The callback message is the request status, of type AisStatus*, which contains one of the following status values:
data_cb_fp. The callback function is invoked once for each message sent from the probe. When the callback is invoked, the callback function is passed a pointer to the process as the callback object. The callback tag is given in the data_cb_tag array. The callback message is the data sent by the probe using the Ais_send() function call.
See Also
activate_probe, bactivate_probe, bdeactivate_probe, bremove_probe, deactivate_probe, remove_probe
Synopsis
#include <Process.h>
AisStatus load_module(
ProbeModule *module,
GCBFuncType ack_cb_fp,
GCBTagType ack_cb_tag);
Parameters
Description
Sends and loads the module from the client side to the target application. Once loaded, the probe expressions available in this probe module can be installed and activated as if they are native in the application.
Note that load_module immediately returns control to the caller upon submitting the request to the daemon. It does not wait until the module has been loaded or has failed to load within the process. If the return value has an AisSeverityCode of ASC_error or worse, the function returns immediately and the user-specified callback will not be invoked.
Exceptions
Return Values
The return value for load_module indicates whether the request to load the indicated module was submitted successfully. It does not indicate whether the request was executed successfully.
Callback Data
When no callback function is provided (when a value of NULL is used as the value for the callback function), the operation is still executed but no callback is called.
The callback function is invoked once for the process for which disconnection is requested. When the callback is invoked, the callback function is passed a pointer to the process as the callback object. The callback message is the request status, of type AisStatus*, which contains one of the following status values:
See Also
bload_module, ProbeExp::call, ProbeModule::get_reference, unload_module
Synopsis
#include <Process.h> Process &operator = (const Process &rhs);
Parameters
Description
Assigns the value of the right operand to the invoking object. The left operand is the invoking object.
For example,
Process rhs, lhs; ... lhs = rhs;
assigns the value of rhs to lhs. Both values would then refer to the same Process, if any.
Return Values
Returns a reference to the invoking object (the left operand).
Synopsis
#include <Process.h> AisStatus query_state(ConnectState *state);
Parameters
Returns the state of the Process. If this state can be determined locally, the function returns immediately. If not, a blocking request is sent to retrieve the state information. For an explanation of the DPCL process states, see DPCL Programming Guide.
Return Values
The return value for query_state indicates whether the state was successfully retrieved.
Synopsis
#include <Process.h>
AisStatus remove_phase(
const Phase &ps,
GCBFuncType ack_cb_fp,
GCBTagType ack_cb_tag);
Parameters
Description
Removes a phase from the application. Data and functions associated with the phase are unaffected by removing it. Existing probe data cannot become associated with a phase except at the time of data allocation, so deleting permanently disassociates data from any other phase.
remove_phase can be called only after the corresponding phase object has been installed by the add_phase or badd_phase call.
Note that remove_phase immediately returns control to the caller upon submitting the request to the daemon. It does not wait until the phase has been removed or has failed to be removed from the process. If the return value has an AisSeverityCode of ASC_error or worse, the function returns immediately and the user-specified callback will not be invoked.
Return Values
The return value for remove_phase indicates whether the request to remove the indicated phase on the process was successfully submitted. It gives no indication of whether the request was successfully executed.
Callback Data
When no callback function is provided (when a value of NULL is used as the value for the callback function), the operation is still executed but no callback is called.
The ack_cb_fp callback function is invoked once, when the acknowledgement of the completion of this operation is received. When the callback is invoked, the callback function is passed a pointer to the process as the callback object. Specify the function name or NULL.
The callback message is the request status, of type AisStatus*, which contains one of the following status values:
See Also
add_phase, badd_phase, bremove_phase, bset_phase_exit, bset_phase_period, get_phase_period, set_phase_exit, set_phase_period
Synopsis
#include <Process.h>
AisStatus remove_probe(
short count,
ProbeHandle *phandle,
GCBFuncType ack_cb_fp,
GCBTagType ack_cb_tag);
Parameters
Description
Removes probe expressions that have been installed in an application. If all probe expressions are installed and deactivated, the probe expressions are removed and a normal return status results. If one or more of the probe expressions are currently active, the expressions are deactivated and removed, and the return status indicates there were active probes at the time of their removal. If one or more of the probes do not exist, all existing probes are removed and the return status indicates a warning. If one or more of the probe expressions exists, but cannot be removed, an error results and none of the probe expressions are removed. If one or more processes are not connected, probe removal takes place within those that are connected, and a warning is issued.
phandle is an input array that is generated by an install_probe or binstall_probe call. It is supplied by the caller and must contain at least count elements. The ith element of the array is a handle, or identifier, that identifies the ith probe expression.
Probe expression removal is atomic in the sense that either all of the probe expressions are removed from a given process, or none are removed. When probes are removed from a process, the process is temporarily stopped, all indicated probes are removed, and the process is resumed.
Note that remove_probe returns control to the caller immediately upon submitting the request to the daemon. It does not wait until the probes have either been removed or have failed to be removed from the process. If the return value has an AisSeverityCode of ASC_error or worse, the function returns immediately and the user-specified callback will not be invoked.
Return Values
The return value for remove_probe indicates whether the request to remove the indicated probes on the process was submitted successfully. It does not indicate whether the request was executed successfully.
Callback Data
When no callback function is provided (when a value of 0 is used as the value for the callback function), the operation is still executed but no callback is called.
The callback function is invoked once, when the acknowledgement that the operation has completed is received. When the callback is invoked, the callback function is passed a pointer to the process as the callback object. The callback message is the request status, of type AisStatus*, which contains one of the following status values:
See Also
activate_probe, bactivate_probe, bdeactivate_probe, binstall_probe, bremove_probe, deactivate_probe, install_probe
Synopsis
#include <Process.h>
AisStatus resume(
GCBFuncType ack_cb_fp,
GCBTagType ack_cb_tag);
Parameters
Description
Resumes execution of an application that has been temporarily suspended by a suspend or bsuspend function. A process must be attached and suspended in order for it to be resumed. Calling this function with a process object that is not attached or suspended will result in the callback receiving an error return value.
Note that resume immediately returns control to the caller upon submitting the request to the daemon. It does not wait until the process has resumed or has failed to resume. If the return value has an AisSeverityCode of ASC_error or worse, the function returns immediately and the user-specified callback will not be invoked.
Return Values
The return value for resume indicates whether the request to resume execution was submitted successfully. It does not indicate whether the request was executed successfully.
Callback Data
When no callback function is provided (when a value of NULL is used as the value for the callback function), the operation is still executed but no callback is called.
The callback function is invoked once, when the acknowledgement that the operation completed is received. When the callback is invoked, the callback function is passed a pointer to the process as the callback object. The callback message is the request status, of type AisStatus*, which contains one of the following status values:
See Also
attach, battach, bresume, bsuspend, suspend
Synopsis
#include <Process.h>
AisStatus send_stdin(
char *buffer,
int size,
GCBFuncType ack_cb_fp,
GCBTagType ack_cb_tag);
Parameters
Description
Provides text to be used as input to the process for the stdin device (file descriptor 0). This function is only appropriate for processes that are created using the create or bcreate member functions. To send an EOF to the stdin device of the controlling POE object, call send_stdin() with the buffer parameter set to NULL.
Note that send_stdin returns control to the caller immediately upon submitting the request to the daemon. It does not wait until the process has received the input.
Return Values
The return value for send_stdin indicates whether the request to provide process input was submitted successfully. It does not indicate whether the request was executed successfully.
Callback Data
The acknowledgement callback function is invoked once, when the buffer has been sent to the process. When the callback is invoked, the callback function is passed a pointer to the process as the callback object. The callback message is the request status, of type AisStatus*, which may contain one of the status values that follow.
See Also
bcreate, create
Synopsis
#include <Process.h>
AisStatus set_phase_exit(
const Phase &ps,
ProbeExp begin_func,
GCBFuncType begin_cb_fp,
GCBTagType begin_cb_tag,
ProbeExp data_func,
GCBFuncType data_cb_fp,
GCBTagType data_cb_tag,
ProbeExp end_func,
GCBFuncType end_cb_fp,
GCBTagType end_cb_tag,
GCBFuncType ack_cb_fp,
GCBTagType ack_cb_tag);
Parameters
Description
Specifies a set of exit functions that get executed when any of the following three events occur:
set_phase_exit can be called only after the corresponding phase object has been installed by the add_phase or badd_phase call.
Note that set_phase_exit immediately returns control to the caller upon submitting the request to the daemon. It does not wait until the exit functions have either been placed in the indicated phase or the operation has failed to complete. If the return value has an AisSeverityCode of ASC_error or worse, the function returns immediately and the user-specified callback will not be invoked.
Each of the phase functions must be signal-safe, and must be loaded into the application before this operation may take place. The function prototypes for the functions are:
void begin_func(void *msg_handle); void data_func(void *msg_handle, void *data); void end_func(void *msg_handle);
Return Values
The return value for set_phase_exit indicates whether the request to set exit functions for the indicated phase on the process was submitted successfully. It does not indicate whether the request was executed successfully.
Callback Data
When no callback function is provided (when a value of NULL is used as the value for the callback function), the operation is still executed but no callback is called.
The following callback functions are invoked each time the corresponding function in the process instrumentation (begin_func, data_func, or end_func) sends a message to the client.
The message format is determined by the function that sends the message.
The ack_cb_fp callback function is invoked once, when the acknowledgement of the completion of this operation is received. When the callback is invoked, the callback function is passed a pointer to the process as the callback object. Specify the function name or NULL.
The callback message is the request status, of type AisStatus*, which contains one of the following status values:
See Also
add_phase, badd_phase, bremove_phase, bset_phase_exit, bset_phase_period, get_phase_period remove_phase, set_phase_period
Synopsis
#include <Process.h>
AisStatus set_phase_period(
const Phase &ps,
float period,
GCBFuncType ack_cb_fp,
GCBTagType ack_cb_tag);
Parameters
Description
This function changes the time interval between successive activations of a phase. Processes that do not have the phase installed result in an informational return code. Processes that are not connected result in a warning return code.
The new period is represented by a positive floating-point value. If the value is smaller than the minimum activation time interval allowed by the setitimer system call, the minimum activation time interval will be used. After the new period is set, the phase will be activated when the new period expires.
set_phase_period can be called only after the corresponding phase object has been installed by the add_phase or badd_phase call.
Note that set_phase_period immediately returns control to the caller upon submitting the request to the daemon. It does not wait until the phase period has either been set or has failed to be set within the process. If the return value has an AisSeverityCode of ASC_error or worse, the function returns immediately and the user-specified callback will not be invoked.
Return Values
The return value for set_phase_period indicates whether the request to set the phase period was submitted successfully. It does not indicate whether the request was executed successfully.
Callback Data
When no callback function is provided (when a value of NULL is used as the value for the callback function), the operation is still executed but no callback is called.
The callback function is invoked once, when the acknowledgement that the operation completed is received. When the callback is invoked, the callback function is passed a pointer to the process as the callback object. The callback message is the request status, of type AisStatus*, which contains one of the following status values:
See Also
add_phase, badd_phase, bremove_phase, bset_phase_exit, bset_phase_period, get_phase_period, remove_phase, set_phase_exit
Synopsis
#include <Process.h>
AisStatus start(
GCBFuncType ack_cb_fp,
GCBTagType ack_cb_tag);
Parameters
Description
Starts execution of a process that has been created but has not yet begun executing. To get a created process running, you must issue one start. Subsequent starts cannot be issued.
Note that start immediately returns control to the caller upon submitting the request to the daemon. It does not wait until the application has either started or failed to start. If the return value has an AisSeverityCode of ASC_error or worse, the function returns immediately and the user-specified callback will not be invoked.
Return Values
The return value for start indicates whether the request to start the process was submitted successfully. It does not indicate whether the request was executed successfully.
Callback Data
When no callback function is provided (when a value of NULL is used as the value for the callback function), the operation is still executed but no callback is called.
The callback function is invoked once, when the acknowledgement that the operation completed is received. When the callback is invoked, the callback function is passed a pointer to the process as the callback object. The callback message is the request status, of type AisStatus*, which contains one of the following status values:
See Also
bcreate, bstart, create
Synopsis
#include <Process.h>
AisStatus suspend(
GCBFuncType fp,
GCBTagType tag);
Parameters
Description
Suspends a process that is executing. A tool must be attached to a process in order to suspend process execution.
Note that suspend immediately returns control to the caller upon submitting the request to the daemon. It does not wait until the application has either been suspended or has failed to be suspended.
Return Values
The return value for suspend indicates whether the request to suspend execution of the process was submitted successfully. It does not indicate whether the request was executed successfully.
Callback Data
When no callback function is provided (when a value of NULL is used as the value for the callback function), the operation is still executed but no callback is called.
The callback function is invoked once, when the acknowledgement that the operation completed is received. When the callback is invoked, the callback function is passed a pointer to the process as the callback object. The callback message is the request status, of type AisStatus*, which contains one of the following status values:
See Also
bresume, bsuspend, resume
Synopsis
#include <Process.h>
AisStatus unload_module(
ProbeModule *module,
GCBFuncType ack_cb_fp,
GCBTagType ack_cb_tag);
Parameters
Description
Unloads the module from all the processes within the Application class. Once unloaded, all the probe handles that refer to this probe module are removed.
Note that unload_module immediately returns control to the caller upon submitting the request to the daemon. It does not wait until the module has either been removed or has failed to be removed from the process. If the return value has an AisSeverityCode of ASC_error or worse, the function returns immediately and the user-specified callback will not be invoked.
Return Values
The return value for unload_module indicates whether the request to remove the indicated module on the process was submitted successfully. It does not indicate whether the request was executed successfully.
Callback Data
When no callback function is provided (when a value of NULL is used as the value for the callback function), the operation is still executed but no callback is called.
The callback function is invoked once, when the acknowledgement that the operation completed is received. When the callback is invoked, the callback function is passed a pointer to the process as the callback object. The callback message is the request status, of type AisStatus*, which contains one of the following status values:
See Also
bload_module, bunload_module, load_module