home *** CD-ROM | disk | FTP | other *** search
/ The Net: Ultimate Internet Guide / WWLCD1.ISO / mac / SiteBldr / AMOVIE / SDK / _SETUP / COMMON.Z / measure.h < prev    next >
Encoding:
Text File  |  1996-02-06  |  8.1 KB  |  225 lines
  1. //==========================================================================;
  2. //
  3. //  THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
  4. //  KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  5. //  IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR
  6. //  PURPOSE.
  7. //
  8. //  Copyright (c) 1992 - 1996  Microsoft Corporation.  All Rights Reserved.
  9. //
  10. //--------------------------------------------------------------------------;
  11.  
  12. /*
  13.    The idea is to pepper the source code with interesting measurements and
  14.    have the last few thousand of these recorded in a circular buffer that
  15.    can be post-processed to give interesting numbers.
  16.  
  17.    WHAT THE LOG LOOKS LIKE:
  18.  
  19.   Time (sec)   Type        Delta  Incident_Name
  20.     0.055,41  NOTE      -.       Incident Nine  - Another note
  21.     0.055,42  NOTE      0.000,01 Incident Nine  - Another note
  22.     0.055,44  NOTE      0.000,02 Incident Nine  - Another note
  23.     0.055,45  STOP      -.       Incident Eight - Also random
  24.     0.055,47  START     -.       Incident Seven - Random
  25.     0.055,49  NOTE      0.000,05 Incident Nine  - Another note
  26.     ------- <etc.  there is a lot of this> ----------------
  27.     0.125,60  STOP      0.000,03 Msr_Stop
  28.     0.125,62  START     -.       Msr_Start
  29.     0.125,63  START     -.       Incident Two   - Start/Stop
  30.     0.125,65  STOP      0.000,03 Msr_Start
  31.     0.125,66  START     -.       Msr_Stop
  32.     0.125,68  STOP      0.000,05 Incident Two   - Start/Stop
  33.     0.125,70  STOP      0.000,04 Msr_Stop
  34.     0.125,72  START     -.       Msr_Start
  35.     0.125,73  START     -.       Incident Two   - Start/Stop
  36.     0.125,75  STOP      0.000,03 Msr_Start
  37.     0.125,77  START     -.       Msr_Stop
  38.     0.125,78  STOP      0.000,05 Incident Two   - Start/Stop
  39.     0.125,80  STOP      0.000,03 Msr_Stop
  40.     0.125,81  NOTE      -.       Incident Three - single Note
  41.     0.125,83  START     -.       Incident Four  - Start, no stop
  42.     0.125,85  START     -.       Incident Five  - Single Start/Stop
  43.     0.125,87  STOP      0.000,02 Incident Five  - Single Start/Stop
  44.  
  45. Number      Average       StdDev     Smallest      Largest Incident_Name
  46.     10     0.000,58     0.000,10     0.000,55     0.000,85 Incident One   - Note
  47.     50     0.000,05     0.000,00     0.000,05     0.000,05 Incident Two   - Start/Stop
  48.      1     -.           -.           -.           -.       Incident Three - single Note
  49.      0     -.           -.           -.           -.       Incident Four  - Start, no stop
  50.      1     0.000,02     -.           0.000,02     0.000,02 Incident Five  - Single Start/Stop
  51.      0     -.           -.           -.           -.       Incident Six   - zero occurrences
  52.    100     0.000,25     0.000,12     0.000,02     0.000,62 Incident Seven - Random
  53.    100     0.000,79     0.000,48     0.000,02     0.001,92 Incident Eight - Also random
  54.   5895     0.000,01     0.000,01     0.000,01     0.000,56 Incident Nine  - Another note
  55.     10     0.000,03     0.000,00     0.000,03     0.000,04 Msr_Note
  56.     50     0.000,03     0.000,00     0.000,03     0.000,04 Msr_Start
  57.     50     0.000,04     0.000,03     0.000,03     0.000,31 Msr_Stop
  58.  
  59.   WHAT IT MEANS:
  60.     The log shows what happened and when.  Each line shows the time at which
  61.     something happened (see WHAT YOU CODE below) what it was that happened
  62.     and (if approporate) the time since the corresponding previous event
  63.     (that's the delta column).
  64.  
  65.     The statistics show how many times each event occurred, what the average
  66.     delta time was, also the standard deviation, largest and smalles delta.
  67.  
  68.    WHAT YOU CODE:
  69.  
  70.    Before anything else executes: - register your ids
  71.  
  72.     int id1     = Msr_Register("Incident One   - Note");
  73.     int id2     = Msr_Register("Incident Two   - Start/Stop");
  74.     int id3     = Msr_Register("Incident Three - single Note");
  75.     etc.
  76.  
  77.    At interesting moments:
  78.  
  79.        // To measure a repetitive event - e.g. end of bitblt to screen
  80.        Msr_Note(Id9);             // e.g. "video frame hiting the screen NOW!"
  81.  
  82.            or
  83.  
  84.        // To measure an elapsed time e.g. time taken to decode an MPEG B-frame
  85.        Msr_Start(Id2);            // e.g. "Starting to decode MPEG B-frame"
  86.          . . .
  87.        MsrStop(Id2);              //      "Finished MPEG decode"
  88.  
  89.    At the end:
  90.  
  91.        HANDLE hFile;
  92.        hFile = CreateFile("Perf.log", GENERIC_WRITE, 0, NULL, CREATE_ALWAYS, 0, NULL);
  93.        Msr_Dump(hFile);           // This writes the log out to the file
  94.        CloseHandle(hFile);
  95.  
  96.            or
  97.  
  98.        Msr_Dump(NULL);            // This writes it to DbgLog((LOG_TRACE,0, ... ));
  99.                                   // but if you are writing it out to the debugger
  100.                                   // then the times are probably all garbage because
  101.                                   // the debugger can make things run awfully slow.
  102.  
  103.     A given id should be used either for start / stop or Note calls.  If Notes
  104.     are mixed in with Starts and Stops their statistics will be gibberish.
  105.  
  106.     If you code the calls in upper case i.e. MSR_START(idMunge); then you get
  107.     macros which will turn into nothing unless PERF is defined.
  108.  
  109.     You can reset the statistical counts for a given id by calling Reset(Id).
  110.     They are reset by default at the start.
  111.     It logs Reset as a special incident, so you can see it in the log.
  112.  
  113.     The log is a circular buffer in storage (to try to minimise disk I/O).
  114.     It overwrites the oldest entries once full.  The statistics include ALL
  115.     incidents since the last Reset, whether still visible in the log or not.
  116. */
  117.  
  118. #ifndef __MEASURE__
  119. #define __MEASURE__
  120.  
  121. #ifdef PERF
  122. #define MSR_INIT() Msr_Init()
  123. #define MSR_TERMINATE() Msr_Terminate()
  124. #define MSR_REGISTER(a) Msr_Register(a)
  125. #define MSR_RESET(a) Msr_Reset(a)
  126. #define MSR_CONTROL(a) Msr_Control(a)
  127. #define MSR_START(a) Msr_Start(a)
  128. #define MSR_STOP(a) Msr_Stop(a)
  129. #define MSR_NOTE(a) Msr_Note(a)
  130. #define MSR_INTEGER(a,b) Msr_Integer(a,b)
  131. #define MSR_DUMP(a) Msr_Dump(a)
  132. #define MSR_DUMPSTATS(a) Msr_DumpStats(a)
  133. #else
  134. #define MSR_INIT()
  135. #define MSR_TERMINATE()
  136. #define MSR_REGISTER(a) 0
  137. #define MSR_RESET(a)
  138. #define MSR_CONTROL(a)
  139. #define MSR_START(a)
  140. #define MSR_STOP(a)
  141. #define MSR_NOTE(a)
  142. #define MSR_INTEGER(a,b)
  143. #define MSR_DUMP(a)
  144. #define MSR_DUMPSTATS(a)
  145. #endif
  146.  
  147. #ifdef __cplusplus
  148. extern "C" {
  149. #endif
  150.  
  151. // This must be called first - (called by the DllEntry)
  152.  
  153. void WINAPI Msr_Init(void);
  154.  
  155.  
  156. // Call this last to clean up (or just let it fall off the end - who cares?)
  157.  
  158. void WINAPI Msr_Terminate(void);
  159.  
  160.  
  161. // Call this to get an Id for an "incident" that you can pass to Start, Stop or Note
  162. // everything that's logged is called an "incident".
  163.  
  164. int  WINAPI Msr_Register(LPTSTR Incident);
  165.  
  166.  
  167. // Reset the statistical counts for an incident
  168.  
  169. void WINAPI Msr_Reset(int Id);
  170.  
  171.  
  172. // Reset all the counts for all incidents
  173. #define MSR_RESET_ALL 0
  174. #define MSR_PAUSE 1
  175. #define MSR_RUN 2
  176.  
  177. void WINAPI Msr_Control(int iAction);
  178.  
  179.  
  180. // log the start of an operation
  181.  
  182. void WINAPI Msr_Start(int Id);
  183.  
  184.  
  185. // log the end of an operation
  186.  
  187. void WINAPI Msr_Stop(int Id);
  188.  
  189.  
  190. // log a one-off or repetitive operation
  191.  
  192. void WINAPI Msr_Note(int Id);
  193.  
  194.  
  195. // log an integer (on which we can see statistics later)
  196. void WINAPI Msr_Integer(int Id, int n);
  197.  
  198.  
  199. // print out all the vaialable log (it may have wrapped) and then the statistics.
  200. // When the log wraps you lose log but the statistics are still complete.
  201. // hFIle==NULL => use DbgLog
  202. // otherwise hFile must have come from CreateFile or OpenFile.
  203.  
  204. void WINAPI Msr_Dump(HANDLE hFile);
  205.  
  206.  
  207. // just dump the statistics - never mind the log
  208.  
  209. void WINAPI Msr_DumpStats(HANDLE hFile);
  210.  
  211. // Type definitions in case you want to declare a pointer to the dump functions
  212. // (makes it a trifle easier to do dynamic linking
  213. // i.e. LoadModule, GetProcAddress and call that)
  214.  
  215. // Typedefs so can declare MSR_DUMPPROC *MsrDumpStats; or whatever
  216. typedef void WINAPI MSR_DUMPPROC(HANDLE hFile);
  217. typedef void WINAPI MSR_CONTROLPROC(int iAction);
  218.  
  219.  
  220. #ifdef __cplusplus
  221. }
  222. #endif
  223.  
  224. #endif // __MEASURE__
  225.