mpiRecorderCreate

Declaration

MPI_RESULT mpiRecorderCreate(MPIRecorder *recorder,
                             MPIControl  control,
                             int32_t        number);

 

Required Header: stdmpi.h

Change History: Modified in 04.00.

Description

mpiRecorderCreate creates a Recorder object identified by number, which is associated with a control object. RecorderCreate is the equivalent of a C++ constructor.

The recorder number specifies which recorder to create. The valid range for the number parameter is -1 to the controller's recordCount (MPIControlConfig.recorderCount). Use a recorder number of -1 to specify the recorder number as the next available recorder.

See MPIControlConfig{.} for details. If the recorder is not enabled or is already in use (another process has called mpiRecorderCreate(...) with the same number parameter), mpiRecorderCreate(...) returns an invalid handle causing subsequent mpiRecorderValidate(...) calls to fail.

It is possible to create a recorder object and not delete it, leaving the resources for the recorder occupied, but forgotten about (abandoned). It is most common to run into this situation when using an index of -1 for the recorder. When developing a program and running it in the debugger, it is common for the developer to exit the program without letting the program clean up its recorder resources.

When number is set to -1, mpiRecorderCreate searches for the next available recorder using the following steps:

  1. Looks for first unused recorder and use it if one exists.
  2. If none, looks for first recorder with a buffer that is full. Most commonly an abandoned recorder.
  3. If none, looks for first recorder with a buffer that is empty and a recorder that is idle.
  4. If none, return the error MPIRecorderMessageNO_RECORDERS_AVAIL.
control
 a handle to a Control object.
number
 An index to the controller's data recorder. If (-1) is specified, the next available recorder object handle is returned. The valid range is from -1 (next available recorder) to the controller's recordCount - 1.
Note: It is required to delete the recorder object to free it for other applications. If the recorder object is not deleted, other applications may assume it is unavailable for use.
Return Values
handle
 to a Recorder object
MPIHandleVOID
 if the Recorder object could not be created

 

See Also

mpiRecorderDelete | mpiRecorderValidate | MPIControlConfig | mpiControlConfigGet | mpiControlConfigSet