Name

bf_process_byfl_file - parse a Byfl binary output file

Synopsis

#include <byfl/bfbin.h>

void bf_process_byfl_file (const char *byfl_filename,
                           bfbin_callback_t *callback_list,
                           void *user_data,
                           int live_input);

Link with -lbfbin.

Description

Overview

Byfl-instrumented applications output detailed performance data to a binary file (by default with a .byfl extension). The bf_process_byfl_file() function simplifies the parsing of such files for use in converting a .byfl file to a different format (e.g., a database) or in processing the data directly (e.g., to compute statistics or visualize patterns).

A .byfl file consists of multiple tables. Each table has a name and contains a number of rows and columns. Each column has a name and a data type that applies to every value in the column. Rows are anonymous.

There are current only three supported data types: unsigned 64-bit integers, strings, and Booleans.

The Byfl binary output file format internally represents two types of tables. "Basic" tables store a complete column header (i.e., column 1 name, column 1 data type, column 2 name, column 2 data type, ...) followed by zero or more rows of data. "Key:value" tables alternate column headers and data values (i.e., column 1 name, column 1 data type, column 1 data, column 2 name, column 2 data type, column 2 data, ...) and represent exactly one row of data. The reason for supporting two types of data is for fast and easy generation of the .byfl file by the Byfl run-time library. bf_process_byfl_file() hides this distinction from the client program by always invoking all of the column-header callback functions before any of the row-data callback functions.

Function arguments

bf_process_byfl_file() presents a callback interface that invokes specified functions for each element of a .byfl file (e.g., table, column header, data element). The byfl_filename argument specifies the name of the .byfl file to parse. The file will be read sequentially so, if desired, it can be a named pipe instead of a normal file. callback_list specifies the set of callback functions that bf_process_byfl_file() can call. It is of type bfbin_callback_t, which is declared as follows:

typedef struct {
  void (*error_cb)(void *user_data, const char *message);

  void (*table_begin_basic_cb)(void *user_data, const char *name);
  void (*table_end_basic_cb)(void *user_data);
  void (*table_begin_keyval_cb)(void *user_data, const char *name);
  void (*table_end_keyval_cb)(void *user_data);

  void (*column_begin_cb)(void *user_data);
  void (*column_uint64_cb)(void *user_data, const char *name);
  void (*column_string_cb)(void *user_data, const char *name);
  void (*column_bool_cb)(void *user_data, const char *name);
  void (*column_end_cb)(void *user_data);

  void (*row_begin_cb)(void *user_data);
  void (*data_uint64_cb)(void *user_data, uint64_t data);
  void (*data_string_cb)(void *user_data, const char *data);
  void (*data_bool_cb)(void *user_data, uint8_t data);
  void (*row_end_cb)(void *user_data);
} bfbin_callback_t;

The user_data argument is an arbitrary pointer that will be passed to each callback function. Client programs will typically point user_data to a structure of local state information.

Finally, live_data is a Boolean that indicates what bf_process_byfl_file() should do upon encountering a premature end of file. If live_data is 0, bf_process_byfl_file() invokes the error_cb callback and aborts processing the .byfl file. If live_data is 1, bf_process_byfl_file() waits until more data are written to the .byfl file then continues processing the file.

Callbacks

Any of the function pointers in bf_process_byfl_file()'s callback_list argument can be NULL. In this case, bf_process_byfl_file() will not invoke a callback function for the associated .byfl file element.

All callback functions receive as their first argument the pointer passed to bf_process_byfl_file().

The following is a description of all of the callback functions in the order they are invoked by bf_process_byfl_file():

• table_begin_basic_cb

• table_begin_keyval_cb

  One of these two callbacks, based on the internal table representation in the Byfi binary output file ("basic" or "key:value"), is invoked at the start of each table. These callbacks are provided the name of the table (e.g., Instruction mix or Basic blocks). Typically, table_begin_basic_cb and table_begin_keyval_cb will point to the same callback function. However, some client programs may wish to process the two tables differently. For example, because a key:value table contains exactly one row, a client program might buffer the column header and data values and transpose these to output one "The value of key is value" string per line of output.

• column_begin_cb

  This callback function is invoked at the start of the column-header definition. It takes no arguments apart from user_data.

• column_uint64_cb

• column_string_cb

• column_bool_cb

  One of these callbacks, based on the column's data type, is invoked for each column of the table. The callback is provided a column name (e.g., Floating-point operations or Bytes stored).

• column_end_cb

  This callback function is invoked after all column headers in the current table have been processed. It takes no arguments apart from user_data.

• row_begin_cb

  This callback function is invoked at the start of each row of data. It takes no arguments apart from user_data.

• row_uint64_cb

• row_string_cb

• row_bool_cb

  One of these callbacks, based on the column's data type, is invoked for each element of the current table row. The callback is provided the value that appears in the corresponding table cell: an unsigned 64-bit integer, a NULL-terminated string, or a Boolean expressed as an unsigned 8-bit integer (0 for false and 1 for true).

• row_end_cb

  This callback function is invoked after each row of a table has been processed. It takes no arguments apart from user_data.

• table_end_basic_cb

• table_end_keyval_cb

  One of these two callbacks, based on the internal table representation in the Byfi binary output file ("basic" or "key:value"), is invoked at the end of each table. They signify that no more rows of data will be written to the current table.

• error_cb

  If bf_process_byfl_file() encounters any type of error during processing, it invokes the error_cb callback with an English-language string describing the error. bf_process_byfl_file() then returns without processing the rest of the .byfl file.

See also

bfbin2cgrind(1), bfbin2hdf5(1), bfbin2csv(1), bfbin2sqlite3(1), bfbin2xmlss(1), bf-clang(1), bf-clang++(1), bf-flang(1), the Byfl home page

Author

Scott Pakin, [email protected]