trin_api.c

fortran并行计算包

/*
 *  (C) 2001 by Argonne National Laboratory
 *      See COPYRIGHT in top-level directory.
 */

/*
 *  @author  Bill Gropp, Anthony Chan
 */

/*
 * API to read a trace file for the SLOG algorithm
 * 
 * We want to defer the choice of representation within the SLOG code
 * while providing an interface the requires the fewest possible
 * copies.
 *
 * This API is optimized for *performance*, not for simplicity.
 *
 * The basic operation is "get next drawable".  All functions
 * assumes some sense of "current" record. Each drawable has the 
 * properties
 *    starttime, endtime 
 *    category (controls shape and color)
 *    coords   (auxillery data for drawing)
 *    text     (popup text input)
 *
 * To allow aggregate of drawables with different categories or texts
 * to be viewed as one drawable, Drawable will be categorized into 2
 * types.  They are called Primitive Drawable and Composite Drawable.
 * Primitive drawable is a simple drawable with a well defined draw() 
 * method + a catgory and text string, e.g. event, state and arrow.  
 * Composite drawable is just a collection of any drawables.  For 
 * simplicity, composite drawable will be assumed to a collection 
 * of primitive drawables in this API.
 *
 * The assumption is that data is read into linear arrays, to
 * optimize performance in the case that there are many small pieces
 * of text and coordinates.
 *
 * An earlier version assumed that category and drawable descriptions
 * were separate.  This version is more general, but requires the
 * user to peek at an object (using Peek_next_kind) to get its kind before 
 * reading it.  Since we encourage a buffered read implementation, this
 * should not introduce any significant inefficiency.
 *
 * One bad thing about this is that the data for a single drawable is not
 * together on a cacheline.  However, the same fields for nearby
 * objects are likely to be nearby, and this approach handles
 * variable length data well.  In fact, for many objects with significant
 * popup data (argument values, source code location), this may provide 
 * *better* cache locality for the drawing information.
 *
 * The reason that we have *not* chosen to define the structure layout for
 * the items read is that this API is used both by the SLOG program *and*
 * by the Display program, in the case where the SLOG Annotation form 
 * is used.
 * 
 * One alternative is to define the structure layout interms of an array of
 * offsets and addresses, and allow the routine to use that info to 
 * decide where to put data.  In that case, it would be possible to use
 * a single call to fill in a data structure.
 */

#include "trin_api.h"

/*@
  TRACE_Open - Open a trace file for input

  Input Parameter:
. filespec - Name of file (or files; see below) to open. 

  Output Parameter:
. fp - Trace file handle (see Notes).

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

  Notes:
  In order to allow TRACE-API to provide its own help message, i.e '-h',
  in 'filespec' string, when the API is used in program like TraceToSlog2.
  Calling program of TRACE_Open() should check if the returned TRACE_file 
  handle 'fp' is NULL instead of just checking of the returned error status.
  If 'fp' is NULL, it means calling program should call TRACE_Get_err_string()
  for either error message or possible help message.  The help message should
  be stored at ierr=0, so the calling program of TRACE_Open() knows if it
  should exit the program with error or normally.
  
  The trace file may be a collection of files, however, to the user of the 
  TRACE API, there is a single (virtual) file.  The 'filespec' is any
  string that is accepted by the TRACE API.  Since the 
  Slog program will only pass this string through (e.g., from the command-line
  to this call), it need not be a file name.  

  Possible interpretations of 'filespec' include a filename, an indirect file
  (i.e., a file that contains the names of other files), a colon separated 
  list of files (i.e., 'file1:file2:file3'), a file pattern (i.e., 'file%d'),
  any of the above along with other options (for the trace file reader), such 
  as limits on the time range or node numbers to accept, or even a shell 
  command (i.e., 'find . -name ''*.log'' ').  'filespec' could contain 
  tracefile selection criteria, e.g. '-s [5,6-8] trc.*'.
  The implementation of the TRACE API must document the acceptable 
  'filespec' so that programs that make use of the TRACE API can provide 
  complete documentation to the user.
  @*/
int TRACE_Open( const char filespec[], TRACE_file *fp )
{}

/*@
  TRACE_Close - Close a trace file

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

  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 pointer 'fp' is set to NULL on a successful close.
@*/
int TRACE_Close( TRACE_file *fp )
{}

/*
  TRACE_Get_total_time - Return the time range covered by an trace file

  Input/Output Parameter:
. fp - Trace file handle

  Output Parameters:
+ starttime - Time when log file begins (no event before this time)
- endtime - Time when log file end (no event after this time)

  Questions:
  Do we want to require this?  In some cases, it may be difficult to 
  return this time.  
*/
/*
int TRACE_Get_total_time( const TRACE_file fp, 
                          double *starttime, double *endtime )
{}
*/

/*@
  TRACE_Peek_next_kind - Determine the kind of the next record

  Input Parameter:
. fp - Trace file handle

  Output Parameters:
. next_kind - Type of next record.  The kind 'TRACE_EOF', 
  which has the value '0', is returned at end-of-file.

  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 structure and ordering of data in a foreign trace file is not defined.
  This routine allows us to find out the type of the next record and then
  use the appropriate 'TRACE_Peek_xxx' routine to discover the size of any 
  variable-sized fields and 'TRACE_Get_xxx' routine to read it.  
  A high-performance implementation of these routines will likely 
  use buffered I/O. 
  @*/
int TRACE_Peek_next_kind( const TRACE_file fp, TRACE_Rec_Kind_t *next_kind )
{}

/* Once the kind of the next item is determined, one of the next 4
   routines may be called */
/* @
  TRACE_Get_next_method - Get the next method description

  Input Parameter:
. fp - Trace file handle

  Output Parameters:
+ method_name - 
. method_extra - 
- method_id - 

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

  Note:
  A typical trace file may have `no` methods.

  Question:
  Should methods have ids so that categories can refer to them by id instead
  of by name?

  How do we ensure that the data areas are large enough?  Do we need 
  a 'TRACE_Peek_next_method' or an input/output parameter indicating the 
  amount of available storage (with an error return of "insufficient 
  memory")?

  @ */
int TRACE_Get_next_method( const TRACE_file fp,
                           char method_name[], char method_extra[], 
                           int *method_id )
{}

/*@
  TRACE_Peek_next_category - Peek at the next category to determine necessary 
  data sizes

  Input Parameter:
. fp - Trace file handle

  Output Parameters:
+ n_legend - Number of characters needed for the legend
. n_label - Number of characters needed for the label
- n_methodIDs - Number of methods (Always zero or one in this version) 

  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 output parameters allow the calling code to allocate space for the 
  variable-length data in a categiry before calling 
  'TRACE_Get_next_category()'.

  @*/
int TRACE_Peek_next_category( const TRACE_file fp,
                              int *n_legend, int *n_label, 
                              int *n_methodIDs )
{}

/*@
  TRACE_Get_next_category - Get the next category description

  Input Parameter:
+ fp - Trace file handle
. legend_max - Allocated size of 'legend_base' array
. label_max - Allocated size of 'label_base' array
- methodID_max - Allocated size of 'methodID_base' array

  Input/Output Parameters:
+ legend_pos - On input, the first available position in 'legend_base'
  On output, changed to indicate the new first available position.
. label_pos - On input, the first available position in 'label_base'
  On output, changed to indicate the new first available position.
- methodID_pos - On input, the first available position in 'methodID_base'
  On output, changed to indicate the new first available position.
 
  Output Parameters:
+ head - Contains basic category info (see the description of 
  'TRACE_Category_head_t')
. n_legend - Size of 'legend_base' array to be used
. legend_base - Pointer to storage to hold legend information
. n_label - Size of 'label_base' array to be used
. label_base - Pointer to storage to hold label information.
               The order of the % tokens specified here, 'label_base', 
               must match the order of operands in the byte array,
               'byte_base[]', specified in 'TRACE_Get_next_primitive()'
               and 'TRACE_Get_next_composite()'.
. n_methodIDs - number of method IDs associated with this category.
- 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:
  The interface to this (and similar routines such as 
  'TRACE_Get_next_primitive()') is designed to give flexibility in how
  data is read.  See 'SLOG2_Get_next_category()' for more details.

  The legend string is used to hold a label for a legend desribing the 
  category.  A typical visualization program will use that text to label 
  and draw a sample of a member from that 
  category.  For example, a blue rectangle with the text 'MPI_Send'.

  The label string is used to describe a particular drawable in that
  category.  For example, a label string of 
.vb
    "Tag = %s\nDestination rank = %s\nmessage size = %s"
.ve
  allows a visualization program to pop up a text box describing any
  drawable while allowing the drawable itself to store only the information 
  that is specific to each instance of the drawable (i.e., the three
  string values referenced).  These string values are provided through the 
  'byte' arguments to 'TRACE_Get_next_primitive'.

  The routine 'TRACE_Peek_next_category' may be used to determine the 
  number of characters of label and legend that are required.
  @*/
int TRACE_Get_next_category( const TRACE_file fp,
                             TRACE_Category_head_t *head,
                             int *n_legend, char legend_base[],
                             int *legend_pos, const int legend_max,
                             int *n_label, char label_base[],
                             int *label_pos, const int label_max,
                             int *n_methodIDs, int methodID_base[],
                             int *methodID_pos, const int methodID_max )
{}
/*
  Old text

. category_methods - Null-terminated array of null-terminated strings 
                     describing methods used to process record-specific data.
- category_method_extra - Extra data for each method
...
                             char category_methods[][], 
                             char category_method_extra[][] )

  To simplify the use of these routines, an empty category method will 
  be interpreted as the default method.  The entries in the category methods
  are interpreted as follows\:
 
+ 0 - Method to use in displaying the legend entry.  
. 1 - Method to use in displaying the popup text.
- >1 - Other popup methods (such as a source code browser).

  The API for describing the methods has not yet been defined, but will likely
  be Java code that works with a display program.  
*/

/*@
  TRACE_Peek_next_primitive - Peek at the next primitive drawable to 
  determine necessary data sizes and time range

  Input Parameter:
. fp - Trace file handle