Additional API Calls in libVTcs
VT_abort
int VT_abort (void)
Description
Abort a
VT_initialize()
or
VT_finalize()
call running concurrently in a different thread.
This call will not block, but it might still take a while before the aborted calls actually return. They will return either successfully (if they have completed without aborting) or with an error code.
Return values
0
if abort request was sent successfully, error code otherwise
VT_clientinit
int VT_clientinit(int procid, const char * clientname, const char * contact)
Description
Initializes communication in a client/server application.
Must be called before
VT_initialize()
in the client of the application. There are three possibilities:
- client is initialized first, which produces a contact string that must be passed to the server (*contact == NULL)
- the server was started first, its contact string is passed to the clients (*contact ==)<result of VT_serverinit() with the prefix "S" - this prefix must be added by the application>
- a process spawns children dynamically, its contact string is given to its children (*contact ==)<result of VT_serverinit() or VT_clientinit()>
Parameters
procid | All clients must be enumerated by the application. This will become the process id of the local client inside its
VT_COMM_WORLD . If the VTserver is used, then enumeration must start at 1 because VTserver always gets rank 0. Threads can be enumerated automatically by Intel® Trace Collector or by the client by calling
VT_registerthread() .
|
clientname | The name of the client. Currently only used for error messages. Copied by Intel® Trace Collector.
|
Return values
contact | Will be set to a string which tells other processes how to contact this process. Guaranteed not to contain spaces. The client may copy this string, but doesn't have to, because Intel® Trace Collector will not free this string until
VT_finalize() is called.
|
Returns error code
VT_serverinit
int VT_serverinit(const char * servername, int numcontacts, const char * contacts[], const char ** contact)
Description
Initializes one process as the server that contacts the other processes and coordinates trace file writing.
The calling process always gets rank 0.
There are two possibilities:
- Collect all information from the clients and pass them here (numcontacts>=0,contacts!=NULL)
- Start the server first, pass its contact string to the clients (numcontacts>=0,contacts==NULL)
This call replaces starting the
VTserver
executable in a separate process. Parameters that used to be passed to the
VTserver
to control tracing and trace writing can be passed to
VT_initialize()
instead.
Parameters
servername | similar to clientname in
VT_clientinit() : the name of the server. Currently only used for error messages. Copied by Intel® Trace Collector.
|
numcontacts | number of client processes
|
contacts | contact string for each client process (order is irrelevant); copied by Intel® Trace Collector
|
Return values
contact | will be set to a string which tells spawned children how to contact this server. Guaranteed not to contain spaces. The server may copy this string, but doesn't have to, because Intel® Trace Collector will not free this string until
VT_finalize() is called.
contact must have been set to
NULL before calling this function.
|
Returns error code
VT_attach
int VT_attach(int root, int comm, int numchildren, int * childcomm)
Description
Connect to several new processes.
These processes must have been spawned already and need to know the contact string of the root process when calling
VT_clientinit()
.
comm == VT_COMM_WORLD
is currently not implemented. It has some design problems: if several children want to use
VT_COMM_WORLD
to recursively spawn more processes, then their parents must also call
VT_attach()
, because they are part of this communicator. If the VTserver is part of the initial
VT_COMM_WORLD
, then
VT_attach()
with
VT_COMM_WORLD
won't work, because the VTserver does not know about the spawned processes and never calls
VT_attach()
.
Parameters
root | rank of the process that the spawned processes will contact
|
comm | either
VT_COMM_SELF or
VT_COMM_WORLD : in the first case root must be
0 and the spawned processes are connected to just the calling process. In the latter case all processes that share this
VT_COMM_WORLD must call
VT_attach() and are included in the new communicator.
root then indicates whose contact infos were given to the children.
|
numchildren | number of children that the spawning processes will wait for
|
Return values
childcomm | an identifier for a new communicator that includes the parent processes in the same order as in their
VT_COMM_WORLD , followed by the child processes in the order specified by their
procid argument in
VT_clientinit() . The spawned processes will have access to this communicator through
VT_get_parent() .
|
Returns error code
VT_get_parent
int VT_get_parent (int * parentcomm)
Description
Returns the communicator that connects the process with its parent, or
VT_COMM_INVALID
if not spawned.
Return values
parentcomm | set to the communicator number that can be used to log communication with parents
|
Returns error code