1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
|
/*************************************************************************
* Copyright (C) 2008 Tavian Barnes <tavianator@gmail.com> *
* *
* This file is part of The Sandglass Library. *
* *
* The Sandglass Library is free software; you can redistribute it *
* and/or modify it under the terms of the GNU Lesser General Public *
* License as published by the Free Software Foundation; either version *
* 3 of the License, or (at your option) any later version. *
* *
* The Sandglass Library is distributed in the hope that it will be *
* useful, but WITHOUT ANY WARRANTY; without even the implied warranty *
* of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
* Lesser General Public License for more details. *
* *
* You should have received a copy of the GNU Lesser General Public *
* License along with this program. If not, see *
* <http://www.gnu.org/licenses/>. *
*************************************************************************/
/*
* libsandglass - a library for extremely high-resolution timing, benchmarking,
* and profiling.
*/
#ifndef SANDGLASS_H_INCLUDED
#define SANDGLASS_H_INCLUDED
#ifdef __cplusplus
/* We've been included from a C++ file; mark everything here as extern "C" */
extern "C" {
#endif
/* A type to represent a clock's time measurement attributes */
enum sandglass_incrementation_t
{
/*
* A clock which only increments during the current process's execution. Less
* precise than a monotonic clock, but more accurate and useful for profiling
* longer operations.
*/
SANDGLASS_INTROSPECTIVE,
/*
* A clock which increments in real-time, regardless of whether the current
* process was executing during that time or not. Allows for greater timing
* resolution, but will be inaccurate if the process is context-switched
* while being timed.
*/
SANDGLASS_MONOTONIC
};
typedef enum sandglass_incrementation_t sandglass_incrementation_t;
/* A type to represent a clock's timing resolution */
enum sandglass_resolution_t
{
/*
* Rely on the kernel to provide time information; less precise, more
* portable. Uses times().
*/
SANDGLASS_SYSTEM,
/*
* Get timing information directly from the processor; more precise, less
* portable. Uses the CLOCK_THREAD_CPUTIME_ID clock for
* SANDGLASS_INTROSPECTIVE mode, and the raw TSC for SANDGLASS_MONOTONIC.
*/
SANDGLASS_CPUTIME
};
typedef enum sandglass_resolution_t sandglass_resolution_t;
/* Attributes of a clock */
struct sandglass_attributes_t
{
sandglass_incrementation_t incrementation;
sandglass_resolution_t resolution;
};
typedef struct sandglass_attributes_t sandglass_attributes_t;
struct sandglass_t
{
/* The attributes of the clock */
sandglass_attributes_t attributes;
/* Units of time which have passed */
long grains;
/* grains/resolution should give elapsed time in seconds */
double resolution;
/*
* Internal fields
*/
/* Adjustment to be added for negative (i.e. overflowed) grains counts */
long adjustment;
/* For SANDGLASS_REALTICKS looping support */
unsigned int i, loops;
/* A field used by sandglass_bench() to store the overhead of
sandglass_begin()/_elapse(), and of looping */
long baseline;
};
typedef struct sandglass_t sandglass_t;
/*
* Creates a timer with at least the precision of `min', and at most the
* precision of `max'. Precisions are compared first by incrementation type:
* all monotonic timers are considered more precise than introspective timers.
* Then, higher resolution timers take precidence.
*
* If `min' is NULL, it defaults to { SANDGLASS_INTROSPECTIVE,
* SANDGLASS_SYSTEM }.
*
* If `max' is NULL, it defaults to at least `min', but not less than
* { SANDGLASS_INTROSPECTIVE, SANDGLASS_CPUTIME }.
*/
int sandglass_create(sandglass_t *sandglass,
const sandglass_attributes_t *min,
const sandglass_attributes_t *max);
int sandglass_begin(sandglass_t *sandglass);
int sandglass_elapse(sandglass_t *sandglass);
/* Use this to prevent a loop from being unrolled */
#define SANDGLASS_NO_UNROLL() __asm__ __volatile__ ("")
/*
* Macros to facilitate correct benchmarking of blocks of code. May be called
* like so:
* sandglass_bench*(&sandglass, f(x))
* or like so:
* sandglass_bench*(&sandglass, {
* f(x);
* g(x);
* });
*/
/* Provides single clock cycle resolution in some cases */
#define sandglass_bench_fine(sandglass, routine) \
do { \
/* Warm up the cache for these functions */ \
sandglass_begin(sandglass); \
sandglass_elapse(sandglass); \
\
/* Time an empty loop for our baseline */ \
sandglass_begin(sandglass); \
for ((sandglass)->i = 0; \
(sandglass)->i < (sandglass)->loops; \
++(sandglass)->i) { \
SANDGLASS_NO_UNROLL(); \
} \
sandglass_elapse(sandglass); \
(sandglass)->baseline = (sandglass)->grains; \
\
/* Warm up the cache for our routine */ \
routine; \
\
/* Time our routine in a loop */ \
sandglass_begin(sandglass); \
for ((sandglass)->i = 0; \
(sandglass)->i < (sandglass)->loops; \
++(sandglass)->i) { \
SANDGLASS_NO_UNROLL(); \
routine; \
SANDGLASS_NO_UNROLL(); \
} \
sandglass_elapse(sandglass); \
\
/* Subtract the baseline and divide by the loop count */ \
(sandglass)->grains -= (sandglass)->baseline; \
(sandglass)->grains /= (sandglass)->loops; \
} while (0)
/* General high resolution timer */
#define sandglass_bench(sandglass, routine) \
do { \
/* Warm up the cache for these functions */ \
sandglass_begin(sandglass); \
sandglass_elapse(sandglass); \
\
/* Time an empty routine for our baseline */ \
sandglass_begin(sandglass); \
sandglass_elapse(sandglass); \
(sandglass)->baseline = (sandglass)->grains; \
\
/* Warm up the cache for our routine */ \
routine; \
\
/* Time the routine */ \
sandglass_begin(sandglass); \
routine; \
sandglass_elapse(sandglass); \
\
/* Subtract the baseline */ \
(sandglass)->grains -= (sandglass)->baseline; \
} while (0)
/* Only executes routine once - useful if routine has side-effects */
#define sandglass_bench_noprecache(sandglass, routine) \
do { \
/* Warm up the cache for these functions */ \
sandglass_begin(sandglass); \
sandglass_elapse(sandglass); \
\
/* Time an empty loop for our baseline */ \
sandglass_begin(sandglass); \
sandglass_elapse(sandglass); \
(sandglass)->baseline = (sandglass)->grains; \
\
/* Time the routine */ \
sandglass_begin(sandglass); \
routine; \
sandglass_elapse(sandglass); \
\
/* Subtract the baseline */ \
(sandglass)->grains -= (sandglass)->baseline; \
} while (0)
#ifdef __cplusplus
}
#endif
#endif /* SANDGLASS_H_INCLUDED */
|
