stopwatch

    #include <mplib1/stopwatch.h>

    struct stopwatch
    {
    struct	timeval start_time;
    struct	timeval cumulative_time;
    char	elps_str[40];
    };


    int init_stopwatch( struct stopwatch *stp );

    int start_stopwatch( struct stopwatch *stp );

    int stop_stopwatch( struct stopwatch *stp );

    int accrete_stopwatch( struct stopwatch *stp_into,
			   struct stopwatch *stp_from );

    char *display_stopwatch( struct stopwatch *stp, int mode );

This set of routines provides a mechanism for timing the execution of an enclosed block of code. They currently give a displayed accuracy to hundredths of a second. The stopwatch structure used contains a time structure for recording when something started, a time structure into which elapsed times are accumulated, and a string buffer for generating ASCII representations of the cumulative data.

init_stopwatch() initialises a stopwatch structure, resetting the cumulative value, the start value and the string buffer.

start_stopwatch() sets the start time of stopwatch structure.

stop_stopwatch() determines the difference between the current time and that held in the start time, and adds this value to the cumulative time.

accrete_stopwatch() adds the cumulative time in the stp_from structure into the cumulative time in the stp_into structure.

display_stopwatch() returns a pointer to an ascii representation of the cumulative time. Currently the only mode that is accepted is 0 which gives a string like

	027.55 seconds

	001529.04 seconds

depending on whether the number of seconds is greater than 999.

How to use these routines.

Suppose we have a block of code we wish to time the execution of. This can be done as follows.


    struct stopwatch this_timer;

    init_stopwatch( &this_timer );
    start_stopwatch( &this_timer );

    /* do the block to be timed */

    stop_stopwatch( &this_timer );
    printf( "The block took %s to complete\n",
	    display_stopwatch( &this_timer, 0 ) );

Now we can move on to a more complex example. In this, we wish to time the various database access functions, to accumulate the database timings and the total time elapsed.

    struct stopwatch db_time,total_db,complete_time;

    init_stopwatch( &complete_time );
    start_stopwatch( &complete_time );

    init_stopwatch( &total_db );

    init_stopwatch( &db_time );
    start_stopwatch( &db_time );
    fetch_driving_db_record( );
    stop_stopwatch( &db_time );
    printf( "fetch_driving_db_record took %s to complete\n",
	    display_stopwatch( &db_time, 0 ) );
    accrete_time( &total_db, &db_time );

    fetch_local_related_data( );		/* non db */

    init_stopwatch( &db_time );
    start_stopwatch( &db_time );
    fetch_associated_db_records( );
    stop_stopwatch( &db_time );
    printf( "fetch_associated_db_records took %s to complete\n",
	    display_stopwatch( &db_time, 0 ) );
    accrete_time( &total_db, &db_time );

    generate_report_line_for_collected_data( );	/* non db */

    stop_stopwatch( &complete_time );
    printf( "Total time: %s  DB time: %s\n",
	    display_stopwatch( &complete_time, 0 ),
	    display_stopwatch( &total_db, 0 ) );

This will produce output in the following style

    fetch_driving_db_record took 014.71 to complete
    fetch_associated_db_records took 007.22 to complete
    Total time: 023.81 seconds  DB time: 021.94 seconds

Note that the total DB time is not the exact sum of the displayed parts. This is because the time held internally is more precise.

Note also that if the individual timings were not required, then the total_db structure is not needed as the database access timings are accumulated in the db_time structure. The resultant code would look like...

    struct stopwatch db_time,complete_time;

    init_stopwatch( &complete_time );
    start_stopwatch( &complete_time );
    init_stopwatch( &db_time );

    start_stopwatch( &db_time );
    fetch_driving_db_record( );
    stop_stopwatch( &db_time );

    fetch_local_related_data( );		/* non db */

    start_stopwatch( &db_time );
    fetch_associated_db_records( );
    stop_stopwatch( &db_time );

    generate_report_line_for_collected_data( );	/* non db */

    stop_stopwatch( &complete_time );
    printf( "Total time: %s  DB time: %s\n",
	    display_stopwatch( &complete_time, 0 ),
	    display_stopwatch( &db_time, 0 ) );