1/* 2 * Copyright (c) 2003 Apple Computer, Inc. All Rights Reserved. 3 * 4 * The contents of this file constitute Original Code as defined in and are 5 * subject to the Apple Public Source License Version 1.2 (the 'License'). 6 * You may not use this file except in compliance with the License. Please 7 * obtain a copy of the License at http://www.apple.com/publicsource and 8 * read it before using this file. 9 * 10 * This Original Code and all software distributed under the License are 11 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 12 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 13 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 14 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 15 * Please see the License for the specific language governing rights and 16 * limitations under the License. 17 */ 18 19/* 20 * cputime.h - high resolution timing module 21 * 22 * This module uses a highly machine-dependent mechanism to get timestamps 23 * directly from CPU registers, without the overhead of a system call. The 24 * timestamps are exported as type CPUTime and you should not concern yourself 25 * with exactly what that is. 26 * 27 * We provide routines to convert a difference between two CPUTimes as a double, 28 * in seconds, milliseconds, and microseconds. Th 29 * 30 * The cost (time) of getting a timestamp (via CPUTimeRead()) generally takes 31 * two or fewer times the resolution period, i.e., less than 80 ns on a 100 MHz 32 * bus machine, often 40 ns. 33 * 34 * The general usage of this module is as follows: 35 * 36 * { 37 * set up test scenario; 38 * CPUTime startTime = CPUTimeRead(); 39 * ...critical timed code here... 40 * CPUTime endTime = CPUTimeRead(); 41 * double elapsedMilliseconds = CPUTimeDeltaMs(startTime, endTime); 42 * } 43 * 44 * It's crucial to place the CPUTimeDelta*() call OUTSIDE of the critical timed 45 * area. It's really cheap to snag the timestamps, but it's not at all cheap 46 * to convert the difference between two timestamps to a double. 47 */ 48 49#ifndef _CPUTIME_H_ 50#define _CPUTIME_H_ 51 52#ifdef __cplusplus 53extern "C" { 54#endif 55 56#include <mach/mach_time.h> 57 58 59typedef uint64_t CPUTime; 60 61/* 62 * Obtain machine-dependent, high resolution, cheap-to-read timestamp. 63 */ 64#define CPUTimeRead() mach_absolute_time() 65 66/* 67 * Convert difference between two CPUTimes into various units. 68 * Implemented as separate functions to preserve as much precision as possible 69 * before required machine-dependent "divide by clock frequency". 70 */ 71extern double CPUTimeDeltaSec(CPUTime from, CPUTime to); // seconds 72extern double CPUTimeDeltaMs(CPUTime from, CPUTime to); // milliseconds 73extern double CPUTimeDeltaUs(CPUTime from, CPUTime to); // microseconds 74 75/* 76 * Calculate the average of an array of doubles. The lowest and highest values 77 * are discarded if there are more than two samples. Typically used to get an 78 * average of a set of values returned from CPUTimeDelta*(). 79 */ 80double CPUTimeAvg( 81 const double *array, 82 unsigned arraySize); 83 84#ifdef __cplusplus 85} 86#endif 87 88#endif /* _CPUTIME_H_ */ 89 90