The PoeAppl class is derived from the Application class, and is used specifically to represent a POE application. Since it is derived from the Application class, all of the Application class member functions are available to objects of the PoeAppl class. In addition, the PoeAppl class has member functions that are relevant only to POE applications. These member functions enable an analysis tool to:
For more information on POE, refer to IBM Parallel Environment for AIX: Operation and Use, Volume 1.
Synopsis
#include <PoeAppl.h> PoeAppl(void); PoeAppl(const PoeAppl copy);
Description
Default constructor. The copy constructor uses the values contained in the copy argument to initialize the new (constructed) object.
Exceptions
Synopsis
#include <PoeAppl.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 an MPI program in a suspended state. All of the processes get created but are suspended at the first executable instruction. The current working directory for the processes is $HOME. Use the start function to allow the MPI program to run.
The POE executable specified in the path parameter is run with the argv and envp parameters provided on the host that is specified by the host parameter. This creates the MPI program, which is set up but not run. The configuration of the MPI program will be found and a Process class will be added to the PoeAppl for each task in the MPI program.
After the create has completed, each process within the PoeAppl will be in a created state and probes may be installed, activated, removed, and so forth.
To find the number of Process objects that are now contained in PoeAppl, use Application::get_count. To access a particular process within PoeAppl, use Application::get_process.
stdio for the MPI program will be handled by POE, depending on the options and environment variables specified for POE. In other words the stdin, stdout and stderr all get funneled through the POE process. The input, output file names, output callbacks and PoeAppl::send_stdin can be used to access the stdio to and from the POE process.
If you pass callback functions to the stdout_cb_fp and stderr_cb_fp parameters, the output from POE will be available in these callbacks. Input to POE can be sent using send_stdin().
Another way to access POE's stdio 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 POE is running. It is expected that the remote_stdin_filename specified will already exist. The files for the remote_stdout_filename and remote_stderr_filename 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 bcreate does not return control to the caller until the new application has been created or has failed to be created. The return value indicates whether the operation succeeded or 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 bcreate indicates whether the application was successfully created.
PoeAppl::bcreate is used to:
Because of this, return values other than the following may be encountered due to errors in the contained DPCL calls.
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 application may be received in different size blocks than were actually sent by the program.
See Also
bdestroy, bstart, create, destroy, get_count, get_process, send_stdin, start, status
Synopsis
#include <PoeAppl.h>
AisStatus binit_procs(
const char *hostname,
int poe_pid);
Parameters
Description
Initializes the PoeAppl class to contain the set of processes used by the MPI program. The process and node configuration of the MPI program is read, and a corresponding set of Process objects are created that contain the process identifier (pid) and hostname of the individual tasks in the MPI program. These Process classes are then added to the PoeAppl object.
To find the number of Process objects that are now contained in PoeAppl, use Application::get_count. To access a particular process within PoeAppl, use Application::get_process.
A subsequent connect must be issued in order to insert instrumentation into the application.
Note that binit_procs does not return control to the caller until either an attempt to obtain the MPI program configuration information fails, or all of the Process classes have attempted to be created.
Return Values
If the MPI program configuration information is successfully found and parsed, the return value indicates whether all binit_procs operations 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.
See Also
bconnect, connect, get_count, get_process, init_procs
Synopsis
#include <PoeAppl.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 an MPI program in a suspended state. All of the processes get created but are suspended at the first executable instruction. The current working directory for the processes is $HOME. Use the start function to allow the MPI program to run.
The POE executable specified in the path parameter is run with the argv and envp parameters that are provided on the host that is specified by the host parameter. This creates the MPI program, which is set up but not run. DPCL finds the configuration of the MPI program and a Process object is added to the PoeAppl for each task in the MPI program.
After the create operation has completed, each process within the PoeAppl will be in a created state, and probes are installed, activated, removed, and so forth.
To find the number of Process objects that are now contained in PoeAppl, use Application::get_count. To access a particular process within the PoeAppl, use Application::get_process.
stdio for the MPI program will be handled by POE depending on the options and environment variables specified for POE. In other words the stdin, stdout and stderr all get funneled through the POE process. The input file name, output file names, output callbacks, and PoeAppl::send_stdin can be used to access the stdio to and from the POE process.
If you pass callback functions to the stdout_cb_fp and stderr_cb_fp parameters, the output from POE will be available in these callbacks. Input to POE can be sent using send_stdin().
Another way to access stdio to POE is to specify the remote filename parameters. In this case stdin, stdout, and stderr can be set to use files on the host where POE is running. In most cases, the remote_stdin_filename that is specified must already exist. The files for the remote_stdout_filename and remote_stderr_filename 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 application 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.The return value indicates whether the request was submitted successfully, but does not indicate whether it was executed successfully, or if it failed.
Return Values
The return value for create indicates whether the request to create an application was successfully submitted, but does not indicate whether it was executed successfully, or if it failed.
Callback Data
The acknowledgement callback function is invoked once when the new application is created. When the callback is invoked, the callback function is passed a pointer to the PoeAppl as the callback object. The callback message is the request status, of type AisStatus, which may contain one of the status values that follow:
PoeAppl::create is implemented using the existing DPCL interface including calls to Process:create and Process::start to initiate POE on the home node, and PoeAppl::init_procs to initialize the PoeAppl class with contained Process classes. Because of this, return values other than the following may be encountered due to errors in the contained DPCL calls:
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 application may be received in different size blocks than were actually sent by the program.
See Also
bcreate, bdestroy, bstart, destroy, get_count, get_process, send_stdin, start
Synopsis
#include <PoeAppl.h>
AisStatus init_procs(
const char *hostname,
int poe_pid,
GCBFuncType fp,
GCBTagType tag);
Parameters
Description
Initializes the PoeAppl class to contain the set of processes used by the MPI program. The process and node configuration of the MPI program is read and a corresponding set of Process classes are created. These Process classes contain the process identifier (pid) and hostname of the individual tasks of the MPI program. These Process classes are then added to the PoeAppl objects.
To find the number of Process objects that are now contained in the PoeAppl, objects use Application::get_count. To access a particular process within the PoeAppl object, use Application::get_process. A subsequent connect must be issued in order to insert instrumentation into the application.
Note that init_procs immediately returns control to the caller upon submitting the request to the daemon. It does not wait until the configuration has been obtained or for the Process classes to be initialized. The acknowledgement callback function receives notification of the success or failure of the PoeAppl initialization.
Return Values
The return value for init_procs indicates whether the requests were submitted successfully, but does not indicate whether the requests themselves were successfully executed.
Callback Data
If the MPI program configuration information is successfully found and parsed, the return value indicates whether all processes have been added to the PoeAppl object, or if 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.
See Also
bconnect, binit_procs, connect, get_count, get_process
Synopsis
#include <PoeAppl.h>
AisStatus send_stdin(
char *buffer,
int size,
GCBFuncType ack_cb_fp,
GCBTagType ack_cb_tag);
Parameters
Description
This function provides text to be used as input to the POE process for the stdin device (file descriptor 0). To send an EOF to the stdin device of the controlling POE process, call send_stdin() with the buffer parameter set to NULL.
In order for send_stdin to be used, the POE application must have been created using the create function.
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.
Return Values
The return value for send_stdin indicates whether the request to provide application 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 POE. When the callback is invoked, the callback function is passed a pointer to the PoeAppl as the callback object. The callback message is the request status, of type AisStatus, which may contain one of the status values values that follow.
See Also
bcreate, create