include/vlc_tick.h

   1 /*****************************************************************************
   2  * vlc_tick.h: high resolution time management functions
   3  *****************************************************************************
   4  * This header provides portable high precision time management functions,
   5  * which should be the only ones used in other segments of the program, since
   6  * functions like gettimeofday() and ftime() are not always supported.
   7  * Most functions are declared as inline or as macros since they are only
   8  * interfaces to system calls and have to be called frequently.
   9  * 'm' stands for 'micro', since maximum resolution is the microsecond.
  10  * Functions prototyped are implemented in interface/mtime.c.
  11  *****************************************************************************
  12  * Copyright (C) 1996, 1997, 1998, 1999, 2000 VLC authors and VideoLAN
  13  * $Id$
  14  *
  15  * Authors: Vincent Seguin <seguin@via.ecp.fr>
  16  *
  17  * This program is free software; you can redistribute it and/or modify it
  18  * under the terms of the GNU Lesser General Public License as published by
  19  * the Free Software Foundation; either version 2.1 of the License, or
  20  * (at your option) any later version.
  21  *
  22  * This program is distributed in the hope that it will be useful,
  23  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  24  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  25  * GNU Lesser General Public License for more details.
  26  *
  27  * You should have received a copy of the GNU Lesser General Public License
  28  * along with this program; if not, write to the Free Software Foundation,
  29  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  30  *****************************************************************************/
  31
  32 #ifndef __VLC_MTIME_H
  33 # define __VLC_MTIME_H 1
  34
  35 /**
  36  * High precision date or time interval
  37  *
  38  * Store a high precision date or time interval. The maximum precision is the
  39  * microsecond, and a 64 bits integer is used to avoid overflows (maximum
  40  * time interval is then 292271 years, which should be long enough for any
  41  * video). Dates are stored as microseconds since a common date (usually the
  42  * epoch). Note that date and time intervals can be manipulated using regular
  43  * arithmetic operators, and that no special functions are required.
  44  */
  45 typedef int64_t vlc_tick_t;
  46 typedef vlc_tick_t mtime_t; /* deprecated, use vlc_tick_t */
  47
  48
  49 /*
  50  * vlc_tick_t <> seconds (sec) conversions
  51  */
  52 #define VLC_TICK_FROM_SEC(sec)   (CLOCK_FREQ * (sec))
  53 #define SEC_FROM_VLC_TICK(vtk)   ((vtk) / CLOCK_FREQ)
  54
  55 #ifdef __cplusplus
  56 #include <type_traits>
  57
  58 template <typename T>
  59 static inline auto vlc_tick_from_sec(T sec)
  60     -> typename std::enable_if<std::is_integral<T>::value, vlc_tick_t>::type
  61 {
  62     return CLOCK_FREQ * sec;
  63 }
  64
  65 /* seconds in floating point */
  66 static inline vlc_tick_t vlc_tick_from_sec(double secf)
  67 {
  68     return (vlc_tick_t)(CLOCK_FREQ * secf); /* TODO use llround ? */
  69 }
  70 #else /* !__cplusplus */
  71 static inline vlc_tick_t vlc_tick_from_seci(int64_t sec)
  72 {
  73     return CLOCK_FREQ * sec;
  74 }
  75 /* seconds in floating point */
  76 static inline vlc_tick_t vlc_tick_from_secf(double secf)
  77 {
  78     return (vlc_tick_t)(CLOCK_FREQ * secf); /* TODO use llround ? */
  79 }
  80
  81 #define vlc_tick_from_sec(sec) _Generic((sec), \
  82         double:  vlc_tick_from_secf(sec), \
  83         float:   vlc_tick_from_secf(sec), \
  84         default: vlc_tick_from_seci(sec) )
  85 #endif /* !__cplusplus */
  86
  87 /* seconds in floating point from vlc_tick_t */
  88 static inline double secf_from_vlc_tick(vlc_tick_t vtk)
  89 {
  90     return (double)vtk / (double)CLOCK_FREQ;
  91 }
  92
  93
  94 /*
  95  * vlc_tick_t <> milliseconds (ms) conversions
  96  */
  97 #if (CLOCK_FREQ % 1000) == 0
  98 #define VLC_TICK_FROM_MS(ms)  ((CLOCK_FREQ / INT64_C(1000)) * (ms))
  99 #define MS_FROM_VLC_TICK(vtk) ((vtk) / (CLOCK_FREQ / INT64_C(1000)))
 100 #elif (1000 % CLOCK_FREQ) == 0
 101 #define VLC_TICK_FROM_MS(ms)  ((ms)  / (INT64_C(1000) / CLOCK_FREQ))
 102 #define MS_FROM_VLC_TICK(vtk) ((vtk) * (INT64_C(1000) / CLOCK_FREQ))
 103 #else /* rounded overflowing conversion */
 104 #define VLC_TICK_FROM_MS(ms)  (CLOCK_FREQ * (ms) / 1000)
 105 #define MS_FROM_VLC_TICK(vtk) ((vtk) * 1000 / CLOCK_FREQ)
 106 #endif /* CLOCK_FREQ / 1000 */
 107
 108
 109 /*
 110  * vlc_tick_t <> microseconds (us) conversions
 111  */
 112 #if (CLOCK_FREQ % 1000000) == 0
 113 #define VLC_TICK_FROM_US(us)    ((CLOCK_FREQ / INT64_C(1000000)) * (us))
 114 #define US_FROM_VLC_TICK(vtk)   ((vtk) / (CLOCK_FREQ / INT64_C(1000000)))
 115 #elif (1000000 % CLOCK_FREQ) == 0
 116 #define VLC_TICK_FROM_US(us)    ((us)  / (INT64_C(1000000) / CLOCK_FREQ))
 117 #define US_FROM_VLC_TICK(vtk)   ((vtk) * (INT64_C(1000000) / CLOCK_FREQ))
 118 #else /* rounded overflowing conversion */
 119 #define VLC_TICK_FROM_US(us)    (CLOCK_FREQ * (us) / INT64_C(1000000))
 120 #define US_FROM_VLC_TICK(vtk)   ((vtk) * INT64_C(1000000) / CLOCK_FREQ)
 121 #endif /* CLOCK_FREQ / 1000000 */
 122
 123
 124 /*
 125  * vlc_tick_t <> nanoseconds (ns) conversions
 126  */
 127 #if (CLOCK_FREQ % 1000000000) == 0
 128 #define VLC_TICK_FROM_NS(ns)    ((ns)  * (CLOCK_FREQ / (INT64_C(1000000000))))
 129 #define NS_FROM_VLC_TICK(vtk)   ((vtk) / (CLOCK_FREQ / (INT64_C(1000000000))))
 130 #elif (1000000000 % CLOCK_FREQ) == 0
 131 #define VLC_TICK_FROM_NS(ns)    ((ns)  / (INT64_C(1000000000) / CLOCK_FREQ))
 132 #define NS_FROM_VLC_TICK(vtk)   ((vtk) * (INT64_C(1000000000) / CLOCK_FREQ))
 133 #else /* rounded overflowing conversion */
 134 #define VLC_TICK_FROM_NS(ns)    (CLOCK_FREQ * (ns) / INT64_C(1000000000))
 135 #define NS_FROM_VLC_TICK(vtk)   ((vtk) * INT64_C(1000000000) / CLOCK_FREQ)
 136 #endif /* CLOCK_FREQ / 1000000000 */
 137
 138
 139 /*
 140  * msftime_t is a time with 100ns resolutions, typically used by Microsoft
 141  */
 142 typedef int64_t msftime_t;
 143
 144 #define MSFTIME_FROM_SEC(sec)       (INT64_C(10000000) * (sec))  /* seconds in msftime_t */
 145 #define MSFTIME_FROM_MS(sec)        (INT64_C(10000) * (sec))     /* milliseconds in msftime_t */
 146
 147 #if (CLOCK_FREQ % 10000000) == 0
 148 #define VLC_TICK_FROM_MSFTIME(msft) ((msft) * (CLOCK_FREQ / INT64_C(10000000))
 149 #define MSFTIME_FROM_VLC_TICK(vtk)  ((vtk)  / (CLOCK_FREQ / INT64_C(10000000))
 150 #elif (10000000 % CLOCK_FREQ) == 0
 151 #define VLC_TICK_FROM_MSFTIME(msft) ((msft) / (INT64_C(10000000) / CLOCK_FREQ))
 152 #define MSFTIME_FROM_VLC_TICK(vtk)  ((vtk)  * (INT64_C(10000000) / CLOCK_FREQ))
 153 #else /* rounded overflowing conversion */
 154 #define VLC_TICK_FROM_MSFTIME(msft) (CLOCK_FREQ * (msft) / INT64_C(10000000))
 155 #define MSFTIME_FROM_VLC_TICK(vtk)  ((vtk)  * INT64_C(10000000) / CLOCK_FREQ)
 156 #endif /* CLOCK_FREQ / 10000000 */
 157
 158 #define vlc_tick_from_timeval(tv) \
 159     (vlc_tick_from_sec( (tv)->tv_sec ) + VLC_TICK_FROM_US( (tv)->tv_usec ))
 160
 161 #define vlc_tick_from_timespec(tv) \
 162     (vlc_tick_from_sec( (tv)->tv_sec ) + VLC_TICK_FROM_NS( (tv)->tv_nsec ))
 163
 164 struct timespec timespec_from_vlc_tick(vlc_tick_t date);
 165
 166
 167 /*****************************************************************************
 168  * MSTRTIME_MAX_SIZE: maximum possible size of mstrtime
 169  *****************************************************************************
 170  * This values is the maximal possible size of the string returned by the
 171  * mstrtime() function, including '-' and the final '\0'. It should be used to
 172  * allocate the buffer.
 173  *****************************************************************************/
 174 #define MSTRTIME_MAX_SIZE 22
 175
 176 /*****************************************************************************
 177  * Prototypes
 178  *****************************************************************************/
 179 VLC_API char * secstotimestr( char *psz_buffer, int32_t secs );
 180
 181 /**
 182  * \defgroup date Timestamps, error-free
 183  * These functions support generating timestamps without long term rounding
 184  * errors due to sample rate conversions.
 185  * \ingroup input
 186  * @{
 187  */
 188 /**
 189  * Timestamps without long-term rounding errors
 190  */
 191 struct date_t
 192 {
 193     vlc_tick_t  date;
 194     uint32_t i_divider_num;
 195     uint32_t i_divider_den;
 196     uint32_t i_remainder;
 197 };
 198
 199 /**
 200  * Initializes a date_t.
 201  *
 202  * \param date date to initialize [OUT]
 203  * \param num divider (sample rate) numerator
 204  * \param den divider (sample rate) denominator
 205  */
 206 VLC_API void date_Init(date_t *restrict date, uint32_t num, uint32_t den);
 207
 208 /**
 209  * Changes the rate of a date_t.
 210  *
 211  * \param date date to change
 212  * \param num divider (sample rate) numerator
 213  * \param den divider (sample rate) denominator
 214  */
 215 VLC_API void date_Change(date_t *restrict date, uint32_t num, uint32_t den);
 216
 217 /**
 218  * Sets the exact timestamp of a date_t.
 219  *
 220  * \param date date to set the timestamp into
 221  * \param value date value
 222  */
 223 static inline void date_Set(date_t *restrict date, vlc_tick_t value)
 224 {
 225     date->date = value;
 226     date->i_remainder = 0;
 227 }
 228
 229 /**
 230  * Gets the current timestamp from a date_t.
 231  *
 232  * \param date date to fetch the timestamp from
 233  * \return date value
 234  */
 235 VLC_USED static inline vlc_tick_t date_Get(const date_t *restrict date)
 236 {
 237     return date->date;
 238 }
 239
 240 /**
 241  * Increments a date.
 242  *
 243  * Moves the date_t timestamp forward by a given number of samples.
 244  *
 245  * \param date date to move forward
 246  * \param count number of samples
 247  * \return timestamp value after incrementing
 248  */
 249 VLC_API vlc_tick_t date_Increment(date_t *restrict date, uint32_t count);
 250
 251 /**
 252  * Decrements a date.
 253  *
 254  * Moves the date_t timestamp backward by a given number of samples.
 255  *
 256  * \param date date to move backward
 257  * \param count number of samples
 258  * \return date value
 259  */
 260 VLC_API vlc_tick_t date_Decrement(date_t *restrict date, uint32_t count);
 261
 262 /** @} */
 263
 264 VLC_API uint64_t NTPtime64( void );
 265 #endif /* !__VLC_MTIME_ */