6.3.6 Log-file functions

Benchmarking has limited value without a proper record of the performance results. The coNCePTuaL run-time library provides functions for writing data to log files. It takes care of much of the work needed to calculate statistics on data columns and to log a thorough experimental setup to every log file.

The library treats a log file as a collection of tables of data. Each table contains a number of rows, one per dynamic invocation of the LOGS statement (see Writing to a log file). Each row contains a number of columns, one per aggregate expression (see Aggregate expressions) expressed statically in a coNCePTuaL program.¹⁷ Log-file functions should be called only if the coNCePTuaL source code accesses a log file (see Writing to a log file).

Function: void ncptl_log_add_comment (const char *key, const char *value)

ncptl_log_add_comment() makes it possible for a backend to add backend-specific <key:value> pairs to the set of prologue or epilogue comments that get written to a log file (see Log-file format). ncptl_log_add_comment() can be called repeatedly. All calls that precede ncptl_log_open() are included in the log-file prologue. All calls that follow ncptl_log_open() are included in the log-file epilogue. Note that ncptl_log_add_comment() makes a copy of key and value, so these need not be heap-allocated.

Function: NCPTL_LOG_FILE_STATE * ncptl_log_open (char *template, ncptl_int processor)

Given a filename template containing a ‘%d’ placeholder and a processor number (i.e., the process’s physical rank in the computation), ncptl_log_open() creates and opens a log file named by the template with ‘%d’ replaced by processor. For example, if template is /home/me/myprog-%d.log and processor is ‘3’, the resulting filename will be /home/me/myprog-3.log. ncptl_log_open() must be called before any of the other ncptl_log_something() functions—except for ncptl_log_add_comment(), which should be called before ncptl_log_open(). ncptl_log_open() returns a pointer to an opaque NCPTL_LOG_FILE_STATE value; the backend will need to pass this pointer to nearly all of the other log-file functions described in this section.

There are three special cases for template. First, if template points to an empty string, all log-file output is sent to the null device (i.e., /dev/null on Unix and Unix-like operating systems). Second, if template is a single dash (‘-’), all log-file output is sent to the standard output device. Third, if template is a single dollar sign (‘$’), all log-file output is buffered in a library-internal string. The string can be retrieved using ncptl_log_get_contents().

Function: char * ncptl_log_generate_uuid (void)

Return a random string of hexadecimal digits formatted as “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx” (36 bytes plus a NULL byte) to pass to ncptl_log_write_prologue(). The caller should ncptl_free() the string when it is no longer needed (generally, as soon as ncptl_log_write_prologue() returns).

Function: void ncptl_log_write_prologue (NCPTL_LOG_FILE_STATE *logstate, char *progname, char *uuid, char *backend_name, char *backend_desc, ncptl_int numtasks, NCPTL_CMDLINE *arglist, int numargs, char **sourcecode)

ncptl_log_write_prologue() standardizes the prologue with which all log files begin. progname is the name of the program executable (argv[0] in C). uuid is a value returned by ncptl_log_generate_uuid(). Note that every process in a program must pass the same value of uuid to ncptl_log_write_prologue(). backend_name is the name of the backend in ‘language_library’ format (e.g., ‘java_rmi’). backend_desc is a brief description of the backend (e.g., ‘Java + RMI’). numtasks is the total number of tasks in the program. arglist is the list of arguments passed to ncptl_parse_command_line() and numargs is the number of entries in that list. sourcecode is the complete coNCePTuaL source code stored as a NULL-terminated list of NULL-terminated strings.

Function: char * ncptl_log_lookup_string (NCPTL_LOG_FILE_STATE *logstate, char *key)

ncptl_log_write_prologue() stores every <key:value> comment it writes into an in-memory database. ncptl_log_lookup_string() searches the comment database for a key and returns the corresponding value. The function returns the empty string if the key is not found in the database. In either case, the caller should not deallocate the result. ncptl_log_lookup_string() is intended to be used to implement coNCePTuaL’s THE VALUE OF construct (see Utilizing log-file comments).

Function: void ncptl_log_write (NCPTL_LOG_FILE_STATE *logstate, int logcolumn, char *description, LOG_AGGREGATE aggregate, double aggregate_param, double value)

Push value value onto column logcolumn of the current table. Gaps between columns are automatically elided. description is used as the column header for column logcolumn. aggregate_param is a parameter needed by certain aggregates. Currently, it used only to represent the target percentile for NCPTL_FUNC_PERCENTILE. Acceptable values for aggregate are defined in Representing aggregate functions.

Function: void ncptl_log_compute_aggregates (NCPTL_LOG_FILE_STATE *logstate)

ncptl_log_compute_aggregates() implements the COMPUTES AGGREGATES construct described in Computing aggregates. When ncptl_log_compute_aggregates() is invoked, the coNCePTuaL run-time library uses the aggregate function specified by ncptl_log_write() to aggregate all of the data that accumulated in each column since the last invocation of ncptl_log_compute_aggregates(). Note that ncptl_log_compute_aggregates() is called implicitly by ncptl_log_commit_data() .

Function: void ncptl_log_commit_data (NCPTL_LOG_FILE_STATE *logstate)

The coNCePTuaL run-time library keeps the current data table in memory and doesn’t write anything to the log file until ncptl_log_commit_data() is called, at which point the run-time library writes all accumulated data to the log file and begins a new data table. Note that ncptl_log_commit_data() is called implicitly by ncptl_log_close(). Furthermore, a backend should call ncptl_log_commit_data() when beginning execution of a new statement in a coNCePTuaL program. For instance, the codegen_c_generic.py backend invokes ncptl_log_commit_data() from code_def_main_newstmt.

Function: void ncptl_log_write_epilogue (NCPTL_LOG_FILE_STATE *logstate)

Write a stock set of comments as an epilogue to the log file.

Function: const char * ncptl_log_get_contents (NCPTL_LOG_FILE_STATE *logstate)

Return the current contents of the log file as a string. The caller must not use the string after the next run-time library call that modifies the log file, modify the string, or free the string. The caller should copy the string (e.g., with ncptl_strdup() ) if any of those actions are necessary. If the the log file does not support random access (because it goes to the standard-output device or the null device), NULL is returned.

Function: void ncptl_log_close (NCPTL_LOG_FILE_STATE *logstate)

Close the log file. No ncptl_log_something() function should be called after ncptl_log_close() is invoked.