include/sphinxbase/profile.h

   1 /* -*- c-basic-offset: 4; indent-tabs-mode: nil -*- */
   2 /* ====================================================================
   3  * Copyright (c) 1999-2001 Carnegie Mellon University.  All rights
   4  * reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions
   8  * are met:
   9  *
  10  * 1. Redistributions of source code must retain the above copyright
  11  *    notice, this list of conditions and the following disclaimer.
  12  *
  13  * 2. Redistributions in binary form must reproduce the above copyright
  14  *    notice, this list of conditions and the following disclaimer in
  15  *    the documentation and/or other materials provided with the
  16  *    distribution.
  17  *
  18  * This work was supported in part by funding from the Defense Advanced
  19  * Research Projects Agency and the National Science Foundation of the
  20  * United States of America, and the CMU Sphinx Speech Consortium.
  21  *
  22  * THIS SOFTWARE IS PROVIDED BY CARNEGIE MELLON UNIVERSITY ``AS IS'' AND
  23  * ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  24  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  25  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY
  26  * NOR ITS EMPLOYEES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  27  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  28  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  29  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  30  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  31  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  32  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  33  *
  34  * ====================================================================
  35  *
  36  */
  37 /*
  38  * profile.h -- For timing and event counting.
  39  *
  40  * **********************************************
  41  * CMU ARPA Speech Project
  42  *
  43  * Copyright (c) 1999 Carnegie Mellon University.
  44  * ALL RIGHTS RESERVED.
  45  * **********************************************
  46  *
  47  * HISTORY
  48  * $Log: profile.h,v $
  49  * Revision 1.10  2005/06/22 03:10:59  arthchan2003
  50  * 1, Fixed doxygen documentation, 2, Added  keyword.
  51  *
  52  * Revision 1.5  2005/06/15 04:21:47  archan
  53  * 1, Fixed doxygen-documentation, 2, Add  keyword such that changes will be logged into a file.
  54  *
  55  * Revision 1.4  2005/04/25 19:22:48  archan
  56  * Refactor out the code of rescoring from lexical tree. Potentially we want to turn off the rescoring if we need.
  57  *
  58  * Revision 1.3  2005/03/30 01:22:48  archan
  59  * Fixed mistakes in last updates. Add
  60  *
  61  *
  62  * 11-Mar-1999  M K Ravishankar (rkm@cs.cmu.edu) at Carnegie Mellon University
  63  *              Added ptmr_init().
  64  *
  65  * 19-Jun-97    M K Ravishankar (rkm@cs.cmu.edu) at Carnegie Mellon University
  66  *              Created from earlier Sphinx-3 version.
  67  */
  68
  69
  70 #ifndef _LIBUTIL_PROFILE_H_
  71 #define _LIBUTIL_PROFILE_H_
  72
  73 #ifdef __cplusplus
  74 extern "C" {
  75 #endif
  76 #if 0
  77 } /* Fool Emacs into not indenting things. */
  78 #endif
  79
  80 /** \file profile.h
  81  * \brief Implementation of profiling, include counting , timing, cpu clock checking
  82  *
  83  * Currently, function host_endian is also in this function. It is
  84  * not documented.
  85  */
  86
  87 #include <stdio.h>
  88
  89 /* Win32/WinCE DLL gunk */
  90 #include <sphinxbase/sphinxbase_export.h>
  91 #include <sphinxbase/prim_type.h>
  92
  93
  94 /**
  95  * \struct pctr_t
  96  *
  97  * Generic event counter for profiling.  User is responsible for allocating an array
  98  * of the desired number.  There should be a sentinel with name = NULL.
  99  */
 100 typedef struct {
 101         char *name;             /**< Counter print name; NULL
 102                                    terminates array of counters
 103                                    Used by pctr_print_all */
 104         int32 count;            /**< Counter value */
 105 } pctr_t;
 106
 107 /**
 108  * operations of pctr_t
 109  */
 110
 111 /**
 112  * Initialize a counter
 113  * @return an initialized counter
 114  */
 115 SPHINXBASE_EXPORT
 116 pctr_t* pctr_new (
 117         char *name   /**< The name of the counter */
 118         );
 119
 120 /**
 121  * Reset a counter
 122  */
 123
 124 SPHINXBASE_EXPORT
 125 void pctr_reset (pctr_t *ctr  /**< A pointer of a counter */
 126         );
 127
 128 /**
 129  * Print a counter
 130  */
 131 SPHINXBASE_EXPORT
 132 void pctr_print(FILE *fp,      /**< A file pointer */
 133                 pctr_t *ctr   /**< A pointer of a counter */
 134         );
 135
 136 /**
 137  * Increment a counter
 138  */
 139 SPHINXBASE_EXPORT
 140 void pctr_increment (pctr_t *ctr, /**< A pointer of a counter */
 141                      int32 inc   /**< The increment of the counter */
 142         );
 143
 144 /**
 145    Free the counter
 146 */
 147 SPHINXBASE_EXPORT
 148 void pctr_free(pctr_t* ctr /**< A pointer of a counter */
 149         );
 150
 151
 152 /**
 153  * \struct ptmr_t
 154  * Generic timer structures and functions for coarse-grained performance measurements
 155  * using standard system calls.
 156  */
 157 typedef struct {
 158         const char *name;               /**< Timer print name; NULL terminates an array of timers.
 159                                            Used by ptmr_print_all */
 160         float64 t_cpu;          /**< CPU time accumulated since most recent reset op */
 161         float64 t_elapsed;              /**< Elapsed time accumulated since most recent reset */
 162         float64 t_tot_cpu;              /**< Total CPU time since creation */
 163         float64 t_tot_elapsed;  /**< Total elapsed time since creation */
 164         float64 start_cpu;              /**< ---- FOR INTERNAL USE ONLY ---- */
 165         float64 start_elapsed;  /**< ---- FOR INTERNAL USE ONLY ---- */
 166 } ptmr_t;
 167
 168
 169
 170 /** Start timing using tmr */
 171 SPHINXBASE_EXPORT
 172 void ptmr_start (ptmr_t *tmr /**< The timer*/
 173         );
 174
 175 /** Stop timing and accumulate tmr->{t_cpu, t_elapsed, t_tot_cpu, t_tot_elapsed} */
 176 SPHINXBASE_EXPORT
 177 void ptmr_stop (ptmr_t *tmr  /**< The timer*/
 178         );
 179
 180 /** Reset tmr->{t_cpu, t_elapsed} to 0.0 */
 181 SPHINXBASE_EXPORT
 182 void ptmr_reset (ptmr_t *tmr  /**< The timer*/
 183         );
 184
 185 /** Reset tmr->{t_cpu, t_elapsed, t_tot_cpu, t_tot_elapsed} to 0.0
 186  */
 187 SPHINXBASE_EXPORT
 188 void ptmr_init (ptmr_t *tmr /**< The timer*/
 189         );
 190
 191
 192 /**
 193  * Reset t_cpu, t_elapsed of all timer modules in array tmr[] to 0.0.
 194  * The array should be terminated with a sentinel with .name = NULL.
 195  */
 196 SPHINXBASE_EXPORT
 197 void ptmr_reset_all (ptmr_t *tmr /**< The timer*/
 198         );
 199
 200 /**
 201  * Print t_cpu for all timer modules in tmr[], normalized by norm (i.e., t_cpu/norm).
 202  * The array should be terminated with a sentinel with .name = NULL.
 203  */
 204 SPHINXBASE_EXPORT
 205 void ptmr_print_all (FILE *fp,    /**< The file pointer */
 206                      ptmr_t *tmr, /**< The timer*/
 207                      float64 norm
 208         );
 209
 210
 211 /**
 212  * Return the processor clock speed (in MHz); only available on some machines (Alphas).
 213  * The dummy argument can be any integer value.
 214  */
 215 SPHINXBASE_EXPORT
 216 int32 host_pclk (int32 dummy);
 217
 218
 219 /*
 220  * Check the native byte-ordering of the machine by writing a magic
 221  * number to a temporary file and reading it back.  * Return value:
 222  * 0 if BIG-ENDIAN, 1 if LITTLE-ENDIAN, -1 if error.
 223  */
 224 SPHINXBASE_EXPORT
 225 int32 host_endian ( void );
 226
 227 #ifdef __cplusplus
 228 }
 229 #endif
 230
 231 #endif