trin_api.c

fortran并行计算包

  Output Parameters:
+ starttime, endtime - time range for drawable
. nt_coords - Number of time coordinates
. ny_coords - Number of y coordinates
- n_bytes - Number of data bytes

  Return Value:
. ierr - Returned integer error status.  It will be used as an argument
  in TRACE_Get_err_string() for possible error string.

  Notes:
  This function really serves two purposes.
  The time range allows the SLOG2 algorithm to determine which treenode a
  drawable should be placed in (which may influence where in memory the data 
  is read by 'TRACE_Get_next_primitive()').  
  The other return values allow the calling code to allocate space for the 
  variable-length data in a drawable before calling 'TRACE_Get_next_primitive'.

  @*/
int TRACE_Peek_next_primitive( const TRACE_file fp,
                               double *starttime, double *endtime,
                               int *nt_coords, int *ny_coords, int *n_bytes )
{}

/*@
  TRACE_Get_next_primitive - Get the next primitive drawable

  Input Parameter:
+ fp - Trace file handle
. tcoord_max - Size of 'tcoord_base'
. ycoord_max - Size of 'ycoord_base'
- byte_max - Size of 'byte_base'

  Input/Output Parameters:
+ tcoord_pos - On input, the first free location in 'tcoord_base'.  Updated
               on output to the new first free location.
. ycoord_pos - The same, for 'ycoord_base'
- byte_pos -  The same, for 'byte_base'

  Output Parameters:
+ starttime, endtime - time range for drawable
. category_index - Index of the category that this drawable belongs to
. nt_coords - Number of time coordinates
. tcoord_base - Pointer to storage to hold time coordinates
. ny_coords - Number of y coordinates
. ycoord_base - Pointer to storage to hold y coordinates
- byte_base - Pointer to storage to hold bytes.  The order of operands
              in the byte array, 'byte_base[]', specified here must match
              the order of the % tokens in the label string, 'label_base',
              in the TRACE_Get_next_category().


  Return Value:
. ierr - Returned integer error status.  It will be used as an argument
  in TRACE_Get_err_string() for possible error string.

  Notes:
  The 'ycoord' values stored in 'ycoord_base + ycoord_pos' represent 
  y-coordinate index values.  These may be simple 'int' values or they may
  be indexes into a y-coordinate mapping table.  For example, a simple 
  trace file format that only records the rank in 'MPI_COMM_WORLD' as the
  y coordinate would return that rank value directly.  A more sophisticated
  trace file format that wished to return the nodename, process id, MPI rank, 
  and thread id would instead return an integer index value into a table 
  that contained that data.  The rows of this table (representing the values 
  for a single index value) are provided through a `routine to be determined`.
  In the latter case, it is better to think of the y coordinate values as
  'thread_id_index' values.

  Rationale:
  The somewhat complex argument list is intended to provide the maximum 
  flexibility in reading and storing the data.  For example, the calling
  program can either allocate new data for each call (using information 
  returned by 'TRACE_Peek_next_primitive') or use preallocated stacks
  (allowing, for example, all 'double' data to be stored contiguously).
  An alternative interface 
  could return a C structure or an instance of a C++ class that contained all
  of this data.  However, that approach imposes a particular representation 
  on any application that chooses to use the code.  If, for example, these
  routines are being used from another language, such as Java, a C or C++
  style interface may be inefficient.  It is expected that this routine will
  appear only within a single higher-level routine that reads data into
  storage organized in a convenient way for the calling application.

  @*/
int TRACE_Get_next_primitive( const TRACE_file fp, 
                              int *category_index, 
                              int *nt_coords, double tcoord_base[],
                              int *tcoord_pos, const int tcoord_max, 
                              int *ny_coords, int ycoord_base[], 
                              int *ycoord_pos, const int ycoord_max,
                              int *n_bytes, char byte_base[],
                              int *byte_pos, const int byte_max )
{}

/*@
  TRACE_Peek_next_composite - Peek at the next composite drawable to
  determine the number of primitive drawables in this composite object,
  time range, and size of pop up data.

  Input Parameter:
. fp - Trace file handle

  Output Parameters:
+ starttime, endtime - time range for drawable
. n_primitives - Number of primitive drawables in this composite object.
- n_bytes - Number of data bytes

  Return Value:
. ierr - Returned integer error status.  It will be used as an argument
  in TRACE_Get_err_string() for possible error string.

  Notes:
  This function really serves two purposes.
  The time range allows the SLOG2 algorithm to determine which treenode this 
  drawable should be placed in (which may influence where in memory the data
  is read by 'TRACE_Get_next_composite()').
  The number of primitives returned allows the calling program to invoke
  'TRACE_Get_next_primitives()' the same number of times to collect all 
  the primitive drawables in the composite object.
  The other return values allow the calling code to allocate space for the
  variable-length data in the composite drawable before calling 
  'TRACE_Get_next_composite()'.

  @*/
int TRACE_Peek_next_composite( const TRACE_file fp,
                               double *starttime, double *endtime,
                               int *n_primitives, int *n_bytes )
{}

/*@
  TRACE_Get_next_composite - Get the header information of the 
                             next composite drawable

  Input Parameter:
+ fp - Trace file handle
- byte_max - Size of 'byte_base'

  Input/Output Parameters:
. byte_pos -  The same, for 'byte_base'

  Output Parameters:
+ starttime, endtime - time range for drawable
. category_index - Index of the category that this drawable belongs to
- byte_base - Pointer to storage to hold bytes.  The order of operands
              in the byte array, 'byte_base[]', specified here must match
              the order of the % tokens in the label string, 'label_base',
              in the TRACE_Get_next_category().


  Return Value:
. ierr - Returned integer error status.  It will be used as an argument
  in TRACE_Get_err_string() for possible error string.

  Notes:
  The interface to this is designed to allow flexibility in how data is read.
  See 'TRACE_Get_next_primitive' for more details.
  @*/
int TRACE_Get_next_composite( const TRACE_file fp,
                              int *category_index,
                              int *n_bytes, char byte_base[],
                              int *byte_pos, const int byte_max )
{}


/*@
  TRACE_Get_position - Return the current position in an trace file

  Input Parameter:
. fp - Trace file handle

  Output Parameter:
. offset - Current file offset.

  Return Value:
. ierr - Returned integer error status.  It will be used as an argument
  in TRACE_Get_err_string() for possible error string.


  Notes:
  This routine and 'TRACE_Set_position' are used in the construction of an
  annotated Slog file.  In an annotated Slog file, the Slog file records the
  location in the original trace file of the records, rather than making a
  copy of the records.  

  If the trace file is actually a collection of files, then that information
  should be encoded within the position.  
  @*/
int TRACE_Get_position( TRACE_file fp, TRACE_int64_t *offset )
{}

/*@
  TRACE_Set_position - Set the current position of a trace file

  Input Parameters:
+ fp - Trace file handle
- offset - Position to set file at

  Return Value:
. ierr - Returned integer error status.  It will be used as an argument
  in TRACE_Get_err_string() for possible error string.

  Notes:
  The file refered to here is relative to the 'filespec' given in a 
  'TRACE_Open' call.  If that 'filespec' describes a collection of real files,
  then this calls sets the position to the correct location in the correct
  real file.
@*/
int TRACE_Set_position( TRACE_file fp, TRACE_int64_t offset )
{}

/*@
  TRACE_Get_err_string - Return the error string corresponding to an error code

  Input Parameter:
. ierr - Error code returned by a TRACE routine

  Return Value:
  Error message string.

  Notes:
  This routine is responsible for providing internationalized (translated)
  error strings.  Implementors may want to consider the GNU 'gettext' style
  functions.  To avoid returning messages of the form 'Message catalog not 
  found', the message catalog routines such as 'catopen' and 'catgets' should
  not be used unless a provision is made to return a message string if no
  message catalog can be found.   The help message for the TRACE-API 
  implementation should be stored at ierr=0, so the calling program of
  TRACE-API knows if it should exit the program normally.
  
 @*/
char *TRACE_Get_err_string( int ierr )
{}

/* 
 * The following allow the input api to specify how to identify the
 * y-axis coordinates
 */
/*@
  TRACE_Peek_next_ycoordmap - Get the size and the description
  of the y-axis coordinate map

  Input Parameter:
. fp - Pointer to a trace file handle

  Output Parameters:
+ n_rows - Number of rows of the y-axis coordinate map
. n_columns - Number of columns of the Yaxis coordinate map
. max_column_name - The maximum length of the column name arrays, i.e.
                    max_column_name = MAX( { column_name[i] } )
. max_title_name - Title string for this map
- n_methodIDs - Number of Method IDs associated with this map

  Return Value:
. ierr - Returned integer error status.  It will be used as an argument
  in TRACE_Get_err_string() for possible error string.

  Notes:
  Both 'max_column_name' and 'max_title_name' includes the NULL character
  needed at the end of the 'title_name' and 'column_names[i]' used in
  'TRACE_Get_next_ycoordmap()'
  @*/
int TRACE_Peek_next_ycoordmap( TRACE_file fp,
                               int *n_rows, int *n_columns,
                               int *max_column_name,
                               int *max_title_name,
                               int *n_methodIDs )
{}

/*@
  TRACE_Get_next_ycoordmap - Return the content of a y-axis coordinate map 


  Output Parameters:

  Input Parameters:
+ fp - Pointer to a trace file handle
. coordmap_max - Allocated size of 'coordmap_base' array
- methodID_max - Allocated size of 'methodID_base' array

  Input/Output Parameters:
+ coordmap_pos - On input, the first free location in 'coordmap_base'.
                 Updated on output to the new first free location.
- methodID_pos - On input, the first available position in 'methodID_base'
                 On output, changed to indicate the new first available
                 position.

  Output Parameters:
+ title_name - character array of length, 'max_title_name', is assumed 
               on input, where 'max_title_name' is defined by 
               'TRACE_Peek_next_ycoordmap()'.  The title name of this 
               map which is NULL terminated will be stored in this
               character array on output.
. column_names - an array of character arrays to store the column names.
                 Each character array is of length of 'max_column_name'.
                 There are 'ncolumns-1' character arrays altogether.
                 where 'ncolumns' and 'max_column_name' are returned by 
                 'TRACE_Peek_next_ycoordmap()'.  The name for the first 
                 column is assumed to be known, only the last 'ncolumns-1' 
                 columns need to be labeled.
. coordmap_sz - Total number of integers in 'coordmap[][]'.
                'coordmap_sz' = 'nrows' * 'ncolumns', 
                otherwise an error will be flagged.
                Where 'nrows' and 'ncolumns' are returned by
                'TRACE_Peek_next_ycoordmap()'
. coordmap_base - Pointer to storage to hold y-axis coordinate map.
. n_methodIDs - number of method IDs associated with this map.
- methodID_base - Pointer to storage to hold method IDs.


  Return Value:
. ierr - Returned integer error status.  It will be used as an argument
  in TRACE_Get_err_string() for possible error string.

  Notes:
  Each entry in y-axis coordinate map is assumed to be __continuously__ 
  stored in 'coordmap_base[]', i.e. every 'ncolumns' consecutive integers 
  in 'coordmap_base[]' is considered one coordmap entry.
  @*/
int TRACE_Get_next_ycoordmap( TRACE_file fp,
                              char *title_name,
                              char **column_names,
                              int *coordmap_sz, int coordmap_base[],
                              int *coordmap_pos, const int coordmap_max,
                              int *n_methodIDs, int methodID_base[],
                              int *methodID_pos, const int methodID_max )
{}