Objects of the Application represent related processes (Process class objects). Specifically, the target application can use objects of this class to represent a set of tasks in a parallel program. Member functions of the Application class enable the analysis tool to:
Synopsis
#include <Application.h> Application(void) Application(const Application ©);
Parameters
Description
Default constructor. The copy constructor uses the values contained in the copy argument to initialize the new (constructed) object.
Exceptions
Synopsis
#include <Application.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 an application. The activation is atomic in the sense that all probes are activated or all probes fail to be activated for any given process within the application. Some processes within the application may successfully activate the probes while other processes fail, but within a process either all probes are successfully activated or none are activated. Probes are activated independently across processes; there is no synchronization to ensure that the probes are activated in all processes at the same time.
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 processes must be in a connected, created, or attached state, and the probes must have been previously installed in those processes.
Note that activate_probe returns control to the caller immediately upon submitting all requests to the daemons. It does not wait until the probes have been activated or have failed to be activated in all processes within 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. The acknowledgement callback function receives notification of the success or failure of the activation. The callback is activated once for each process within the application.
Return Values
The return value indicates whether the activation requests were successfully submitted, but indicates nothing about whether the requests themselves executed successfully.
Callback Data
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, bdisconnect, bprobe_deactivate, bprobe_install, class Process, connect, disconnect, GCBFuncType, probe_deactivate, probe_install
Synopsis
#include <Application.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 each connected process within the application. 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 add_phase returns control to the caller immediately upon submitting all requests to the daemons. It does not wait until the phase has been installed or has failed to be installed in all processes within 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. The acknowledgement callback function receives notification of the success or failure of the installation. The callback is activated once for each process within the application. The initialization function must be loaded into the application 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
The return value indicates whether the requests for phase addition were successfully submitted, but indicates nothing about whether the requests themselves were successfully executed.
Callback Data
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
badd_phase, bconnect, bdisconnect, class GenCallBack, class ProbeMod, class Process, connect, disconnect, GCBFuncType, GCBTagType, Process::alloc_mem, Process::free_mem
Synopsis
#include <Application.h> AisStatus add_process(const Process *p);
Parameters
Description
Adds a process to the set of processes managed by the application. This operation acts locally within the end-user tool. It does not attempt to connect to the process. The process state (e.g. connected or attached) is not required to match the state of all other processes within the application.
The index of a process may change when new processes are added to or removed from an application. Other operations do not change process indexes.
Return Values
The return value indicates whether the process addition was successful.
See Also
connect, bconnect, bdisconnect, disconnect, get_count, get_process, remove_process
Synopsis
#include <Application.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 each process in the application. 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 any or all of the application processes where the data is allocated.
If the block of probe data is to be used by a Phase object, alloc_mem 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 all of the processes within 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. The probe expression representing the allocation is returned immediately whether or not the allocations succeed. The returned probe expression may be used as a data reference on any process where 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 where the allocation failed, that probe expression will fail to install. Similarly, installation will fail if one attempts to install the probe in a process where the data was not allocated.
stat indicates whether all requests for allocation were successfully submitted. If all requests are successfully submitted stat is given the value ASC_success. If some request cannot be submitted then stat is given the value ASC_operation_failed. It reflects the highest severity encountered.
Return Values
Returns a probe expression that may be used as a valid reference to the data on any process in which the data has been successfully allocated.
Callback Data
The callback function is invoked once for each process for which data allocation 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
add_phase, badd_phase, balloc_mem, bfree_mem, free_mem, status
Synopsis
#include <Application.h>
AisStatus attach(
GCBFuncType fp,
GCBTagType tag);
Parameters
Description
Attaches to all processes within an application. When multiple tools are connected to a process or application, only one tool 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 execution. Processes must first be connected or created before they can be attached.
This function not only attaches to the processes managed by this application, but also suspends their execution in the same way that a call to the suspend or bsuspend function would. To resume execution of this application's processes, the analysis tool can call the resume or bresume function.
Note that attach returns control to the caller immediately upon submitting all requests to the daemons. It does not wait until all processes within the application have attached or have failed to attach. The acknowledgement callback function receives notification of the success or failure of the activation. The callback is activated once for each process within the application.
Return Values
The return value for attach indicates whether the requests were successfully submitted, but indicates nothing about whether the requests themselves executed successfully.
Callback Data
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 <Application.h>
AisStatus bactivate_probe(
short count,
ProbeHandle *phandle);
Parameters
Description
Activates a list of probes that have been installed within an application. The activation is atomic in the sense that all probes are activated or all probes fail to be activated for any given process within the application. Some processes within the application may successfully activate the probes while other processes fail, but within a process either all probes are successfully activated or none are activated. Probes are activated independently across processes; there is no synchronization to ensure that the probes are activated in all processes at the same time.
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 processes must be in a connected, created, or attached state, and the probes must have been previously installed in those processes.
Note that the function submits the requests to activate the probes and waits until the requests have completed. The function Application::status(int index) may be queried to determine whether the operation succeeded or failed on any given process.
Return Values
The return value indicates whether all of the requests for activation were successfully executed. The return value reflects the highest severity encountered across all processes.
See Also
activate_probe, bconnect, bdisconnect, bprobe_deactivate, bprobe_install, connect, disconnect, probe_deactivate, probe_install
Synopsis
#include <Application.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 each connected process within the application. 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 this function submits the requests to add the phase and waits until the requests have completed. The return value indicates whether all of the requests executed successfully. The function Application::status(int index) may be queried to determine whether the operation succeeded or failed on any given process.
The initialization function must be signal-safe, and must be loaded into the application 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
The return value indicates whether requests to add phases all processes executed successfully. The return value reflects the highest severity encountered across all processes.
Callback Data
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, bconnect, bdisconnect, class ProbeModule, connect, disconnect, Process::alloc_mem, Process::free_mem
Synopsis
#include <Application.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
This function allocates a block of probe data in each process in the application. 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 any or all of the application processes where the data is allocated. The initial value of the data is as specified, or 0 if not specified.
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 or call.
Note that balloc_mem does not return control to the caller until it has either succeeded or failed on all of the processes within the application. If the allocation succeeds it returns a valid probe expression data reference and stat is given the value ASC_success. If the allocation fails on some process then stat is given a non-successful error return value, and any probe that references the returned value of balloc_mem will fail to install on that process.
The function Application::status(int index) may be queried to determine whether the operation succeeded or failed on any given process.
Return Values
Returns a probe expression that may be used as a valid reference to the data on any process in which the data has been successfully allocated.
See Also
alloc_mem, bfree_mem, free_mem, status
Synopsis
#include <Application.h> AisStatus battach(void);
Description
Attaches to all processes within an application. When multiple tools are connected to a process or application, only one tool can be attached at a time. Attaching to a process or application allows the tool to control the execution directly (for example, suspending and resuming execution). Processes must first be connected or created before they can be attached.
This function not only attaches to the processes managed by this application, but also suspends their execution in the same way that a call to the suspend or bsuspend function would. To resume execution of this application's processes, the analysis tool can call the resume or bresume function.
Note that battach does not return control to the caller until all attachments have either succeeded or failed. The return value indicates whether all attachments succeeded or some succeeded and some failed. The function Application::status(int index) may be queried to determine whether the operation succeeded or failed on any given process.
Return Values
The return value for battach indicates whether the individual attachments themselves were successfully established. The return value reflects the highest severity encountered across all processes.
See Also
attach, bdetach, detach status
Synopsis
#include <Application.h> AisStatus bconnect(void);
Description
Connects to all processes within an application. Connecting 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 and alter its control flow.
Connections from multiple DPCL-based tools to the same processes within the application are allowed.
Note that bconnect does not return control to the caller until all connections have either succeeded or failed. The return value indicates whether all connections succeeded or some succeeded and some failed. You may call the function Application::status(int index) to determine whether the operation succeeded or failed on any given process.
Return Values
The return value for bconnect indicates whether the connections themselves were successfully established. The return value reflects the highest severity encountered across all processes.
See Also
bdisconnect, connect, disconnect, PoeAppl::binit_procs, PoeAppl::init_procs, status
Synopsis
#include <Application.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 each of the processes within the application to deactivate the list of probes represented by the array. Probes are activated atomically for each process in the sense that the process is temporarily stopped, all probes on the list are deactivated, then the process is restarted. None of the probes in the array are left active.
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 all processes in the application. The return value indicates whether all connections succeeded or some succeeded and some failed. The function Application::status(int index) may be queried to determine whether the operation succeeded or failed on any given process.
Return Values
The return value for bdeactivate_probe indicates whether the deactivations were successfully completed. The return value reflects the highest severity encountered across all processes.
See Also
activate_probe, bactivate_probe, binstall_probe, deactivate_probe, install_probe, status
Synopsis
#include <Application.h> AisStatus bdestroy(void);
Description
Destroys or terminates all processes within the application. If this is called from a PoeAppl object, the POE process itself is also destroyed. This object must first be attached before it can be destroyed. If an application has just been created, and is in PRC_created_state, it may be destroyed without attaching.
When calling bdestroy() on a PoeAppl object, note that a return value of ASC_already_destroyed may be encountered. This can occur because once DPCL starts to destroy the components of the POE job, POE itself starts cleaning up by destroying its own components.
Note that bdestroy does not return control to the caller until all processes within the application have been destroyed. The return value indicates whether all terminations succeeded, or some succeeded and some failed. You may call the function Application::status(int index) determine whether the operation succeeded or failed on any given process.
Return Values
The return value for bdestroy indicates whether the processes terminated successfully. The return value reflects the highest severity encountered across all processes.
See Also
attach, battach, destroy, status
Synopsis
#include <Application.h> AisStatus bdetach(void);
Description
Detaches all processes in the application. Process control flow, such suspending and resuming processes, 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, etc. can still take place.
Note that bdetach does not return control to the caller until all processes within the application have been detached. The return value indicates whether all processes successfully detached or some succeeded and some failed. The function Application::status(int index) may be queried to determine whether the operation succeeded or failed on any given process.
Return Values
The return value for bdetach indicates whether all processes were successfully detached. The return value reflects the highest severity encountered across all processes.
See Also
attach, battach, detach, status
Synopsis
#include <Application.h> AisStatus bdisconnect(void);
Description
Disconnects from all processes within an application. Disconnecting from an application process removes the application environment created by a connection. All instrumentation and data are removed from the application process.
Note that bdisconnect does not return control to the caller until all processes within the application have either succeeded or failed in disconnecting. The function Application::status(int index) may be queried to determine whether the operation succeeded or failed on any given process.
Return Values
The return value for bdisconnect indicates whether the connections were successfully terminated. The return value reflects the highest severity encountered across all processes.
See Also
bconnect, connect, disconnect, status
Synopsis
#include <Application.h>
AisStatus bexecute(
ProbeExp pexp,
GCBFuncType data_cb_fp,
GCBTagType data_cb_tag);
Parameters
Description
Executes a probe expression in each process within an application. The expression is executed once in each process, 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 within all processes in an application. The function Application::status(int index) may be queried to determine whether the operation succeeded or failed on any given process.
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 execution succeeded or failed.
See Also
Class ProbeExp, execute, status, sigaction (UNIX)
Synopsis
#include <Application.h> AisStatus bfree_mem(ProbeExp pexp);
Parameters
Description
Deallocates a block of dynamically allocated probe memory for every process in the application. 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_mem does not return control to the caller until all processes within the application have either succeeded or failed in deallocating the block of memory. The function Application::status(int index) may be queried to determine whether the operation succeeded or failed on any given process.
Return Values
The return value for bfree_mem indicates whether all deallocation requests executed successfully. The return value reflects the highest severity encountered across all processes.
See Also
alloc_mem, balloc_mem, free_mem, status
Synopsis
#include <Application.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 each process in the application. 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 of the expressions are installed. There is no synchronization across processes to assure that all processes install all probes. The return value indicates whether all probes were installed, or whether one or more processes were unable to install the expressions as requested.
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 Ais_send 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 all processes within the application. The function Application::status(int index) may be queried to determine whether the operation succeeded or failed on any given process.
Return Values
The return value for binstall_probe indicates whether the probe installations were successful. The return value reflects the highest severity encountered across all processes.
Callback Data
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, Class ProbeExp, Class Probehandle, install_probe, status
Synopsis
#include <Application.h> AisStatus bload_module(ProbeModule* module);
Parameters
Description
Sends and loads the module from the DPCL analysis tool to all the processes within the Application class. 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 been installed or has failed to be installed in all processes within the application. The function Application::status(int index) may be queried to determine whether the operation succeeded or failed on any given 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 installations were successful. The return value reflects the highest severity encountered across all processes.
See Also
bunload_module, load_module, unload_module
Synopsis
#include <Application.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 it.
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 all processes within the application. The function Application::status(int index) may be queried to determine whether the operation succeeded or failed on any given process.
Return Values
The return value for bremove_phase indicates whether the phase was successfully removed from all processes. The return value reflects the highest severity encountered across all processes.
See Also
add_phase, badd_phase, class Phase, remove_phase, status
Synopsis
#include <Application.h>
AisStatus bremove_probe(
short count,
ProbeHandle *phandle);
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 an appropriate warning. If one or more of the probe expressions exists but cannot be removed, an error results and as many probes as can be 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 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. Probe expressions are removed in a process-by-process manner. There is no synchronization between processes to guarantee that all expressions are removed from all processes. One process may succeed while another one fails.
Note that bremove_probe does not return control to the caller until the probes have either been removed or have failed to be removed from all processes within the application. The function Application::status(int index) may be queried to determine whether the operation succeeded or failed on any given process.
Return Values
The return value for bremove_probe indicates whether all probes in the list were successfully removed from all processes. The return value reflects the highest severity encountered across all processes.
See Also
activate_probe, bactivate_probe, bdeactivate_probe, binstall_probe, Class ProbeHandle, deactivate_probe, install_probe, remove_probe, status
Synopsis
#include <Application.h> AisStatus bresume(void);
Description
Resumes execution of an application that has been temporarily suspended by a suspend or bsuspend function. Execution resumes on a process-by-process basis within the application.
A process must be attached in order for it to be resumed. A bresume request issued against an application that contains processes that are not attached or that are not suspended will result in an error return value.
Note that bresume does not return control to the caller until the all processes within the application have resumed or failed to resume. The function Application::status(int index) may be queried to determine whether the operation succeeded or failed on any given process.
Return Values
The return value for bresume indicates whether all processes were successfully resumed. The return value reflects the highest severity encountered across all processes.
See Also
attach, battach, bconnect, bdetach, bdisconnect, bsuspend, connect, detach, disconnect, resume, status, suspend
Synopsis
#include <Application.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 badd_phase or add_phase call.
Note that set_phase_exit returns control to the caller immediately 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 has 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 remove_phase indicates whether the requests to remove the indicated phase on all processes in the application were successfully submitted. It gives no indication of whether the requests were successfully executed.
Callback Data
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, remove_phase, set_phase_exit, status
Synopsis
#include <Application.h>
AisStatus bset_phase_period(
const Phase &ps,
float period);
Parameters
Description
Changes the time interval between successive activations of a phase. The interval change occurs on a process-by-process basis for all processes within the application. If a process does not have the phase installed, an informational return code results. 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 or add_phase call.
Note that bset_phase_period does not return control to the caller until the phase period has either been set or has failed to be set in all processes within the application. The function Application::status(int index) may be queried to determine whether the operation succeeded or failed on any given process.
Return Values
The return value for bset_phase_period indicates whether the phase period was successfully set on all processes. The return value reflects the highest severity encountered across all processes.
See Also
add_phase, badd_phase, bremove_phase, get_phase_period, remove_phase, set_phase_period, status
Synopsis
#include <Application.h> AisStatus bstart(void);
Description
Starts the execution of an application that has been created but has not yet begun executing. It does this by issuing a start to each process contained in the application. To get a created application running, you must issue one start. Subsequent starts cannot be issued.
Note that bstart does not return control to the caller until the application has started or failed to start. The function Application::status(int index) may be queried to determine whether the operation succeeded or failed on any given process.
Return Values
The return value for bstart indicates whether the application was successfully started.
See Also
bdestroy, Class PoeAppl, destroy, Process::bcreate, Process::create, start, status
Synopsis
#include <Application.h> AisStatus bsuspend(void);
Description
Suspends an application that is executing. Applications are suspended within the application on a process-by-process basis. A tool must be attached to a process in order to suspend execution.
Note that bsuspend does not return control to the caller until each process within the application has either been suspended or has failed to be suspended. The function Application::status(int index) may be queried to determine whether the operation succeeded or failed on any given process.
Return Values
The return value for bsuspend indicates whether all processes within the application were successfully suspended. The return value reflects the highest severity encountered across all processes.
See Also
bresume, resume, status, suspend
Synopsis
#include <Application.h> AisStatus bunload_module(ProbeModule *module);
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 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 all processes within the application. The function Application::status(int index) may be queried to determine whether the operation succeeded or failed on any given process.
Return Values
The return value for bunload_module indicates whether the probe module was successfully removed from all processes. The return value reflects the highest severity encountered across all processes.
See Also
bload_module, load_module, status, unload_module
Synopsis
#include <Application.h>
AisStatus connect(
GCBFuncType fp,
GCBTagType tag);
Parameters
Description
Connect to all processes within an application. 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, alter its control flow, etc.
Connections from multiple DPCL analysis tools to the same processes within the application are allowed.
The function submits the requests to connect the processes and returns immediately. The callback function receives notification of each connection's success or failure.
Return Values
The return value for connect indicates whether the requests for connection to all processes in the application were successfully submitted. It does not indicate whether the requests themselves were executed successfully.
Callback Data
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, PoeAppl::binit_procs, PoeAppl::init_procs,
Synopsis
#include <Application.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 processes 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 suspended, 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 returns control immediately 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 all requests were successfully submitted and gives no indication whatever about the success or failure of the execution of those requests.
Return Values
The return value for deactivate_probe indicates whether the deactivations were successfully submitted.
Callback Data
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, Process::activate_probe Process::bactivate_probe, Process::bdeactivate_probe
Synopsis
#include <Application.h>
AisStatus destroy(
GCBFuncType fp,
GCBTagType tag);
Parameters
Description
Destroys or terminates all processes within the application. If this is called from a PoeAppl object, the POE process itself is also destroyed. This object must first be attached before it can be destroyed. If an application has just been created, and is in PRC_created_state, it may be destroyed without attaching.
When calling destroy() on a PoeAppl object, note that a return value of ASC_already_destroyed may be encountered in some of the callbacks. This can occur because once DPCL starts to destroy the components of the POE job, POE itself starts cleaning up by destroying its own components.
Note that destroy returns control to the caller immediately. It does not wait until all processes within the application have been destroyed. The return value indicates whether the requests were successfully submitted, but gives no indication of whether the requests themselves were successfully executed.
Return Values
The return value for destroy indicates whether the terminations were successfully requested.
Callback Data
The callback function is invoked once for each process for which destruction 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
attach, battach, bdestroy
Synopsis
#include <Application.h>
AisStatus detach(
GCBFuncType fp,
GCBTagType tag);
Parameters
Description
Detaches all processes in the application. Process control flow, such as suspending and resuming processes, 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, etc. can still take place.
Note that detach returns control to the caller immediately upon issuing all requests to detach from the processes. The return value indicates whether all requests were successfully submitted.
Return Values
The return value for detach indicates whether all requests were successfully submitted.
Callback Data
The callback function is invoked once for each process for which detachment 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
attach, battach, bdetach
Synopsis
#include <Application.h>
AisStatus disconnect(
GCBFuncType fp,
GCBTagType tag);
Parameters
Description
Disconnects from all processes within an application. Disconnecting from an application process removes the application environment created by a connection. All instrumentation and data are removed from the application process.
Note that this function submits the requests to disconnect the processes and returns immediately. The callback function receives notification of each disconnection's success or failure.
Return Values
The return value for disconnect indicates whether the requests for disconnection were successfully submitted, but indicates nothing about whether the requests themselves were successfully executed.
Callback Data
The callback function is invoked once for each 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
bconnect, bdisconnect, connect
Synopsis
#include <Application.h>
AisStatus execute(
ProbeExp pexp,
GCBFuncType data_cb_fp,
GCBTagType data_cb_tag,
GCBFuncType ack_cb_fp,
GCBTagType ack_cb_tag);
Parameters
Description
Executes a probe expression within all processes of an application. 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 returns control to the caller immediately upon submitting its request to the daemons. It does not wait until the probe expression has either 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. The callback is executed once for each process within the application.
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 execution was successfully submitted, but indicates nothing about whether the request was successfully executed.
Callback Data
The callback function is invoked when execution 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
bexecute, Class ProbeExp
Synopsis
#include <Application.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 every process in the application. 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 returns control to the caller immediately upon submitting its request to free the data. It does not wait until the data has either been deallocated or has failed to be deallocated. 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. The callback is executed once for each process within the application.
Return Values
The return value for free_mem indicates whether the requests for deallocation were successfully submitted, but indicates nothing about whether the requests themselves were successfully executed.
Callback Data
The callback function is invoked once for each process for which deallocation 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
alloc_mem, balloc_mem, bfree_mem
Synopsis
#include <Application.h> int get_count(void) const;
Description
Returns the number of processes currently included in the application.
Return Values
The return value for get_count indicates the number of Process objects in the application.
See Also
get_process
Synopsis
#include <Application.h> Process get_process(int i) const;
Parameters
Description
Returns the ith Process object of the application.
The index of a process may change when new processes are added to or removed from a application. Other operations do not change process indexes.
Return Values
Returns the ith Process object if the index is valid, in other words, 0 <= i <= get_count(), or an invalid process if the index is not valid.
See Also
get_count
Synopsis
#include <Application.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 each process in the application. Probe expressions are installed atomically in the sense that, within each process, either all of the probe expressions in the request are installed in the process, or none are installed. There is no synchronization across processes to assure that all processes install all probes. The return value indicates whether all requests to have probes installed were successfully submitted.
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 returns control to the caller immediately upon submitting all requests to the daemons. It does not wait until all probe expressions have 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 requests for probes to be installed were successfully submitted. It gives no indication of whether those requests were successfully executed.
Callback Data
The ack_cb_fp callback function is invoked once for each process for which probe installation 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:
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 <Application.h>
AisStatus load_module(
ProbeMod *module,
GCBFuncType ack_cb_fp,
GCBTagType ack_cb_tag);
Parameters
Description
This function sends and loads the module from the DPCL analysis tool to all the processes within the Application class. Once loaded, the probe expressions available in this probe module can be installed and activated as if they are native to the application.
Note that load_module returns control to the caller immediately upon submitting all requests to the daemons. It does not wait until the module has been loaded or has failed to be loaded within all processes within 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.
Each subsequent call to this function, with the same module specified, loads another copy of the module.
Exceptions
Return Values
The return value for load_module indicates whether the requests to load the indicated module on all processes were successfully submitted. It gives no indication of whether those requests were successfully executed.
Callback Data
The callback function is invoked once for each 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, bunload_module, Class ProbeModule
Synopsis
#include <Application.h> Application &operator = (const Application &rhs);
Parameters
Description
Assigns the value of the right operand to the invoking object. The left operand is the invoking object.
For example,
Application rhs, lhs; ... lhs = rhs;
assigns the value of rhs to lhs. This yields a new copy of the application object.
Return Values
Returns a reference to the invoking object (the left operand).
Synopsis
#include <Application.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 a phase are unaffected by removing the phase. Existing probe data can only be associated with a phase at the time that the data is allocated. As a result, deleting a phase permanently disassociates the 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 when it submits all requests to the daemons. It does not wait until the phase has been removed or has failed to be removed from all processes within 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 remove_phase indicates whether the requests to remove the indicated phase on all processes in the application were successfully submitted. It gives no indication of whether the requests were successfully executed.
Callback Data
When no callback function is provided, that is, 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 ack_cb_fp callback function is invoked once for each process for which phase removal 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
add_phase, badd_phase, bremove_phase
Synopsis
#include <Application.h>
AisStatus remove_probe(
short count,
ProbeHandle *phandle,
GCBFuncType ack_cb_fp,
GCBTagType ack_cb_tag);
Parameters
Description
Deletes or 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 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 one or more processes are not connected, the probes are removed within those that are connected, and a warning is issued.
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 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 suspended, all indicated probes are removed, and the process is resumed. Probe expressions are removed in a process-by-process basis. There is no synchronization between processes to guarantee that all indicated expressions are removed from all processes. One process may succeed while another fails.
Note that remove_probe immediately returns control to the caller upon submitting all requests to the daemons. It does not wait until the probes have been removed or have failed to be removed from all processes within 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 remove_probe indicates whether the requests to remove the indicated probes on all processes in the application were successfully submitted. It gives no indication of whether the requests were successfully executed.
Callback Data
The callback function is invoked once for each process for which probe removal 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
activate_probe, bactivate_probe, bdeactivate_probe, binstall_probe, bremove_probe, deactivate_probe, install_probe
Synopsis
#include <Application.h> AisStatus remove_process(int i);
Parameters
Description
Removes the ith Process object of the application. Parameter i must reflect a valid index; 0 <= i < get_count(). The process itself is not altered or affected in any way.
The index of a process may change when new processes are added to or removed from a application. Other operations do not change process indexes.
Return Values
The return value for remove_process indicates whether the process was successfully removed. The return value reflects the highest severity encountered across all processes.
See Also
add_process, bconnect, bdisconnect, connect, disconnect, get_count
Synopsis
#include <Application.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. Execution resumes on a process-by-process basis. A process must be attached and suspended for it to be resumed. A resume request issued against an application that contains processes that are not attached or not suspended will result in an error return value being passed to the callback.
Note that resume immediately returns control to the caller upon submitting all requests to the daemons. It does not wait until the processes have resumed or have 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 all requests to resume execution were successfully submitted. It gives no indication of whether the requests were successfully executed.
Callback Data
The callback function is invoked once for each process to be resumed. 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, bresume, bsuspend, detach, suspend
Synopsis
#include <Application.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 processes of the application for the stdin device; file descriptor 0. In order for send_stdin to be used, the Process objects contained within the Application must have been created using the create function. To send an EOF to the stdin device of the Process objects contained within the Application, call send_stdin() with the buffer parameter set to NULL.
Note that send_stdin immediately returns control to the caller upon submitting the request to the daemon. It does not wait until the application has received the input. 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 send_stdin indicates whether the request to provide application input was successfully submitted. It gives no indication of whether the request was successfully executed.
Callback Data
The acknowledgement callback function is invoked once for each process in the application 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
PoeAppl::bcreate, PoeAppl::create, Process::bcreate, Process::create
Synopsis
#include <Application.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 to be 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 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 been placed in the indicated phase, or the operation 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);
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 remove_phase indicates whether the requests to remove the indicated phase on all processes in the application were successfully submitted. It gives no indication of whether the requests were successfully executed.
Callback Data
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 for each process for which phase removal 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
add_phase, badd_phase, bremove_phase, bset_phase_exit, remove_phase, status
Synopsis
#include <Application.h>
AisStatus set_phase_period(
const Phase &ps,
float period,
GCBFuncType ack_cb_fp,
GCBTagType ack_cb_tag);
Parameters
Description
Changes the time interval between successive activations of a phase. The interval change occurs on a process-by-process basis for all processes within the application. If a process does not have the phase installed, an information return code results. 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 all requests to the daemons. It does not wait until the phase period has been set or has failed to be set 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 set_phase_period indicates whether all requests to set the phase period were successfully submitted. It gives no indication of whether the requests were successfully executed.
Callback Data
The callback function is invoked once for each process for which setting the new period for a phase 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
add_phase, badd_phase, bremove_phase, bset_phase_period, get_phase_period, remove_phase, status
Synopsis
#include <Application.h>
AisStatus start(
GCBFuncType ack_cb_fp,
GCBTagType ack_cb_tag);
Parameters
Description
Starts the execution of an application that has been created but has not yet begun executing. It does this by issuing a start to each process contained in the application. To get a created application running, you must issue one start. Subsequent starts cannot be issued.
Note that start returns control to the caller immediately upon submitting the request to the daemon. It does not wait until the application has been started or failed to be started. 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 application was successfully submitted. It gives no indication of whether the request was successfully executed.
Callback Data
The 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. The callback message is the request status, of type AisStatus*, which contains one of the following status values:
See Also
bstart, PoeAppl::bcreate, PoeAppl::create
Synopsis
#include <Application.h> AisStatus status(int i);
Parameters
Description
Returns status for the ith Process object of the application. Parameter i must reflect a valid index; 0 <= i < get_count(). The returned value reflects the status value of the most recently executed Application class call.
Exceptions
Return Values
The meaning of the return value for status is determined by the most recent call that was executed.
See Also
get_count
Synopsis
#include <Application.h>
AisStatus suspend(
GCBFuncType fp,
GCBTagType tag);
Parameters
Description
Suspends an application that is executing. Applications are suspended on a process-by-process basis. The DPCL analysis tool must be attached to a process in order to suspend its execution.
Note that suspend immediately returns control to the caller upon submitting all requests to the daemons. It does not wait until processes within the application have been suspended or have failed to be suspended.
Return Values
The return value for suspend indicates whether all requests to suspend processes were successfully submitted. It gives no indication of whether the requests were successfully executed.
Callback Data
The callback function is invoked once for each process for which suspension 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
attach, battach, bdetach, bresume, bsuspend, detach, resume
Synopsis
#include <Application.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 probe handles that refer to this probe module are automatically removed.
Note that unload_module immediately returns control to the caller upon submitting all requests to the daemons. It does not wait until the module has been removed or has failed to be removed from all processes within 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 unload_module indicates whether the requests to remove the indicated module on all processes were successfully submitted. It gives no indication of whether the requests were successfully executed.
Callback Data
The callback function is invoked once for each process for which object removal 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, bunload_module, load_module