TLA  Line data    Source code

       1                 : /*-------------------------------------------------------------------------
       2                 :  *
       3                 :  * instr_time.h
       4                 :  *    portable high-precision interval timing
       5                 :  *
       6                 :  * This file provides an abstraction layer to hide portability issues in
       7                 :  * interval timing.  On Unix we use clock_gettime(), and on Windows we use
       8                 :  * QueryPerformanceCounter().  These macros also give some breathing room to
       9                 :  * use other high-precision-timing APIs.
      10                 :  *
      11                 :  * The basic data type is instr_time, which all callers should treat as an
      12                 :  * opaque typedef.  instr_time can store either an absolute time (of
      13                 :  * unspecified reference time) or an interval.  The operations provided
      14                 :  * for it are:
      15                 :  *
      16                 :  * INSTR_TIME_IS_ZERO(t)            is t equal to zero?
      17                 :  *
      18                 :  * INSTR_TIME_SET_ZERO(t)           set t to zero (memset is acceptable too)
      19                 :  *
      20                 :  * INSTR_TIME_SET_CURRENT(t)        set t to current time
      21                 :  *
      22                 :  * INSTR_TIME_SET_CURRENT_LAZY(t)   set t to current time if t is zero,
      23                 :  *                                  evaluates to whether t changed
      24                 :  *
      25                 :  * INSTR_TIME_ADD(x, y)             x += y
      26                 :  *
      27                 :  * INSTR_TIME_SUBTRACT(x, y)        x -= y
      28                 :  *
      29                 :  * INSTR_TIME_ACCUM_DIFF(x, y, z)   x += (y - z)
      30                 :  *
      31                 :  * INSTR_TIME_GET_DOUBLE(t)         convert t to double (in seconds)
      32                 :  *
      33                 :  * INSTR_TIME_GET_MILLISEC(t)       convert t to double (in milliseconds)
      34                 :  *
      35                 :  * INSTR_TIME_GET_MICROSEC(t)       convert t to uint64 (in microseconds)
      36                 :  *
      37                 :  * INSTR_TIME_GET_NANOSEC(t)        convert t to uint64 (in nanoseconds)
      38                 :  *
      39                 :  * Note that INSTR_TIME_SUBTRACT and INSTR_TIME_ACCUM_DIFF convert
      40                 :  * absolute times to intervals.  The INSTR_TIME_GET_xxx operations are
      41                 :  * only useful on intervals.
      42                 :  *
      43                 :  * When summing multiple measurements, it's recommended to leave the
      44                 :  * running sum in instr_time form (ie, use INSTR_TIME_ADD or
      45                 :  * INSTR_TIME_ACCUM_DIFF) and convert to a result format only at the end.
      46                 :  *
      47                 :  * Beware of multiple evaluations of the macro arguments.
      48                 :  *
      49                 :  *
      50                 :  * Copyright (c) 2001-2023, PostgreSQL Global Development Group
      51                 :  *
      52                 :  * src/include/portability/instr_time.h
      53                 :  *
      54                 :  *-------------------------------------------------------------------------
      55                 :  */
      56                 : #ifndef INSTR_TIME_H
      57                 : #define INSTR_TIME_H
      58                 : 
      59                 : 
      60                 : /*
      61                 :  * We store interval times as an int64 integer on all platforms, as int64 is
      62                 :  * cheap to add/subtract, the most common operation for instr_time. The
      63                 :  * acquisition of time and converting to specific units of time is platform
      64                 :  * specific.
      65                 :  *
      66                 :  * To avoid users of the API relying on the integer representation, we wrap
      67                 :  * the 64bit integer in a struct.
      68                 :  */
      69                 : typedef struct instr_time
      70                 : {
      71                 :     int64       ticks;          /* in platforms specific unit */
      72                 : } instr_time;
      73                 : 
      74                 : 
      75                 : /* helpers macros used in platform specific code below */
      76                 : 
      77                 : #define NS_PER_S    INT64CONST(1000000000)
      78                 : #define NS_PER_MS   INT64CONST(1000000)
      79                 : #define NS_PER_US   INT64CONST(1000)
      80                 : 
      81                 : 
      82                 : #ifndef WIN32
      83                 : 
      84                 : 
      85                 : /* Use clock_gettime() */
      86                 : 
      87                 : #include <time.h>
      88                 : 
      89                 : /*
      90                 :  * The best clockid to use according to the POSIX spec is CLOCK_MONOTONIC,
      91                 :  * since that will give reliable interval timing even in the face of changes
      92                 :  * to the system clock.  However, POSIX doesn't require implementations to
      93                 :  * provide anything except CLOCK_REALTIME, so fall back to that if we don't
      94                 :  * find CLOCK_MONOTONIC.
      95                 :  *
      96                 :  * Also, some implementations have nonstandard clockids with better properties
      97                 :  * than CLOCK_MONOTONIC.  In particular, as of macOS 10.12, Apple provides
      98                 :  * CLOCK_MONOTONIC_RAW which is both faster to read and higher resolution than
      99                 :  * their version of CLOCK_MONOTONIC.
     100                 :  */
     101                 : #if defined(__darwin__) && defined(CLOCK_MONOTONIC_RAW)
     102                 : #define PG_INSTR_CLOCK  CLOCK_MONOTONIC_RAW
     103                 : #elif defined(CLOCK_MONOTONIC)
     104                 : #define PG_INSTR_CLOCK  CLOCK_MONOTONIC
     105                 : #else
     106                 : #define PG_INSTR_CLOCK  CLOCK_REALTIME
     107                 : #endif
     108                 : 
     109                 : /* helper for INSTR_TIME_SET_CURRENT */
     110                 : static inline instr_time
     111 GNC    10899829 : pg_clock_gettime_ns(void)
     112                 : {
     113                 :     instr_time  now;
     114                 :     struct timespec tmp;
     115                 : 
     116        10899829 :     clock_gettime(PG_INSTR_CLOCK, &tmp);
     117        10899829 :     now.ticks = tmp.tv_sec * NS_PER_S + tmp.tv_nsec;
     118                 : 
     119        10899829 :     return now;
     120                 : }
     121                 : 
     122                 : #define INSTR_TIME_SET_CURRENT(t) \
     123                 :     ((t) = pg_clock_gettime_ns())
     124                 : 
     125                 : #define INSTR_TIME_GET_NANOSEC(t) \
     126                 :     ((int64) (t).ticks)
     127                 : 
     128                 : 
     129                 : #else                           /* WIN32 */
     130                 : 
     131                 : 
     132                 : /* Use QueryPerformanceCounter() */
     133                 : 
     134                 : /* helper for INSTR_TIME_SET_CURRENT */
     135                 : static inline instr_time
     136                 : pg_query_performance_counter(void)
     137                 : {
     138                 :     instr_time  now;
     139                 :     LARGE_INTEGER tmp;
     140                 : 
     141                 :     QueryPerformanceCounter(&tmp);
     142                 :     now.ticks = tmp.QuadPart;
     143                 : 
     144                 :     return now;
     145                 : }
     146                 : 
     147                 : static inline double
     148                 : GetTimerFrequency(void)
     149                 : {
     150                 :     LARGE_INTEGER f;
     151                 : 
     152                 :     QueryPerformanceFrequency(&f);
     153                 :     return (double) f.QuadPart;
     154                 : }
     155                 : 
     156                 : #define INSTR_TIME_SET_CURRENT(t) \
     157                 :     ((t) = pg_query_performance_counter())
     158                 : 
     159                 : #define INSTR_TIME_GET_NANOSEC(t) \
     160                 :     ((int64) ((t).ticks * ((double) NS_PER_S / GetTimerFrequency())))
     161                 : 
     162                 : #endif                          /* WIN32 */
     163                 : 
     164                 : 
     165                 : /*
     166                 :  * Common macros
     167                 :  */
     168                 : 
     169                 : #define INSTR_TIME_IS_ZERO(t)   ((t).ticks == 0)
     170                 : 
     171                 : 
     172                 : #define INSTR_TIME_SET_ZERO(t)  ((t).ticks = 0)
     173                 : 
     174                 : #define INSTR_TIME_SET_CURRENT_LAZY(t) \
     175                 :     (INSTR_TIME_IS_ZERO(t) ? INSTR_TIME_SET_CURRENT(t), true : false)
     176                 : 
     177                 : 
     178                 : #define INSTR_TIME_ADD(x,y) \
     179                 :     ((x).ticks += (y).ticks)
     180                 : 
     181                 : #define INSTR_TIME_SUBTRACT(x,y) \
     182                 :     ((x).ticks -= (y).ticks)
     183                 : 
     184                 : #define INSTR_TIME_ACCUM_DIFF(x,y,z) \
     185                 :     ((x).ticks += (y).ticks - (z).ticks)
     186                 : 
     187                 : 
     188                 : #define INSTR_TIME_GET_DOUBLE(t) \
     189                 :     ((double) INSTR_TIME_GET_NANOSEC(t) / NS_PER_S)
     190                 : 
     191                 : #define INSTR_TIME_GET_MILLISEC(t) \
     192                 :     ((double) INSTR_TIME_GET_NANOSEC(t) / NS_PER_MS)
     193                 : 
     194                 : #define INSTR_TIME_GET_MICROSEC(t) \
     195                 :     (INSTR_TIME_GET_NANOSEC(t) / NS_PER_US)
     196                 : 
     197                 : #endif                          /* INSTR_TIME_H */