time.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 1999 - 2005, Digium, Inc.
00005  *
00006  * Mark Spencer <markster@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*! \file
00020  * \brief Time-related functions and macros
00021  */
00022 
00023 #ifndef _ASTERISK_TIME_H
00024 #define _ASTERISK_TIME_H
00025 
00026 #ifdef HAVE_SYS_TIME_H
00027 #include <sys/time.h>
00028 #endif
00029 
00030 #include "asterisk/inline_api.h"
00031 
00032 /* We have to let the compiler learn what types to use for the elements of a
00033    struct timeval since on linux, it's time_t and suseconds_t, but on *BSD,
00034    they are just a long. */
00035 extern struct timeval tv;
00036 typedef typeof(tv.tv_sec) ast_time_t;
00037 typedef typeof(tv.tv_usec) ast_suseconds_t;
00038 
00039 /*!
00040  * \brief Computes the difference (in seconds) between two \c struct \c timeval instances.
00041  * \param end the end of the time period
00042  * \param start the beginning of the time period
00043  * \return the difference in seconds
00044  */
00045 AST_INLINE_API(
00046 int64_t ast_tvdiff_sec(struct timeval end, struct timeval start),
00047 {
00048    int64_t result = end.tv_sec - start.tv_sec;
00049    if (result > 0 && end.tv_usec < start.tv_usec)
00050       result--;
00051    else if (result < 0 && end.tv_usec > start.tv_usec)
00052       result++;
00053 
00054    return result;
00055 }
00056 )
00057 
00058 /*!
00059  * \brief Computes the difference (in microseconds) between two \c struct \c timeval instances.
00060  * \param end the end of the time period
00061  * \param start the beginning of the time period
00062  * \return the difference in microseconds
00063  */
00064 AST_INLINE_API(
00065 int64_t ast_tvdiff_us(struct timeval end, struct timeval start),
00066 {
00067    return (end.tv_sec - start.tv_sec) * (int64_t) 1000000 +
00068       end.tv_usec - start.tv_usec;
00069 }
00070 )
00071 
00072 /*!
00073  * \brief Computes the difference (in milliseconds) between two \c struct \c timeval instances.
00074  * \param end end of the time period
00075  * \param start beginning of the time period
00076  * \return the difference in milliseconds
00077  */
00078 AST_INLINE_API(
00079 int64_t ast_tvdiff_ms(struct timeval end, struct timeval start),
00080 {
00081    /* the offset by 1,000,000 below is intentional...
00082       it avoids differences in the way that division
00083       is handled for positive and negative numbers, by ensuring
00084       that the divisor is always positive
00085    */
00086    int64_t sec_dif = (int64_t)(end.tv_sec - start.tv_sec) * 1000;
00087    int64_t usec_dif = (1000000 + end.tv_usec - start.tv_usec) / 1000 - 1000;
00088    return  sec_dif + usec_dif;
00089 }
00090 )
00091 
00092 /*!
00093  * \brief Returns true if the argument is 0,0
00094  */
00095 AST_INLINE_API(
00096 int ast_tvzero(const struct timeval t),
00097 {
00098    return (t.tv_sec == 0 && t.tv_usec == 0);
00099 }
00100 )
00101 
00102 /*!
00103  * \brief Compres two \c struct \c timeval instances returning
00104  * -1, 0, 1 if the first arg is smaller, equal or greater to the second.
00105  */
00106 AST_INLINE_API(
00107 int ast_tvcmp(struct timeval _a, struct timeval _b),
00108 {
00109    if (_a.tv_sec < _b.tv_sec)
00110       return -1;
00111    if (_a.tv_sec > _b.tv_sec)
00112       return 1;
00113    /* now seconds are equal */
00114    if (_a.tv_usec < _b.tv_usec)
00115       return -1;
00116    if (_a.tv_usec > _b.tv_usec)
00117       return 1;
00118    return 0;
00119 }
00120 )
00121 
00122 /*!
00123  * \brief Returns true if the two \c struct \c timeval arguments are equal.
00124  */
00125 AST_INLINE_API(
00126 int ast_tveq(struct timeval _a, struct timeval _b),
00127 {
00128    return (_a.tv_sec == _b.tv_sec && _a.tv_usec == _b.tv_usec);
00129 }
00130 )
00131 
00132 /*!
00133  * \brief Returns current timeval. Meant to replace calls to gettimeofday().
00134  */
00135 AST_INLINE_API(
00136 struct timeval ast_tvnow(void),
00137 {
00138    struct timeval t;
00139    gettimeofday(&t, NULL);
00140    return t;
00141 }
00142 )
00143 
00144 /*!
00145  * \brief Returns the sum of two timevals a + b
00146  */
00147 struct timeval ast_tvadd(struct timeval a, struct timeval b);
00148 
00149 /*!
00150  * \brief Returns the difference of two timevals a - b
00151  */
00152 struct timeval ast_tvsub(struct timeval a, struct timeval b);
00153 
00154 /*!
00155  * \since 12
00156  * \brief Formats a duration into HH:MM:SS
00157  *
00158  * \param duration The time (in seconds) to format
00159  * \param buf A buffer to hold the formatted string'
00160  * \param length The size of the buffer
00161  */
00162 void ast_format_duration_hh_mm_ss(int duration, char *buf, size_t length);
00163 
00164 
00165 /*!
00166  * \brief Calculate remaining milliseconds given a starting timestamp
00167  * and upper bound
00168  *
00169  * If the upper bound is negative, then this indicates that there is no
00170  * upper bound on the amount of time to wait. This will result in a
00171  * negative return.
00172  *
00173  * \param start When timing started being calculated
00174  * \param max_ms The maximum number of milliseconds to wait from start. May be negative.
00175  * \return The number of milliseconds left to wait for. May be negative.
00176  */
00177 int ast_remaining_ms(struct timeval start, int max_ms);
00178 
00179 /*!
00180  * \brief Returns a timeval from sec, usec
00181  */
00182 AST_INLINE_API(
00183 struct timeval ast_tv(ast_time_t sec, ast_suseconds_t usec),
00184 {
00185    struct timeval t;
00186    t.tv_sec = sec;
00187    t.tv_usec = usec;
00188    return t;
00189 }
00190 )
00191 
00192 /*!
00193  * \brief Returns a timeval corresponding to the duration of n samples at rate r.
00194  * Useful to convert samples to timevals, or even milliseconds to timevals
00195  * in the form ast_samp2tv(milliseconds, 1000)
00196  */
00197 AST_INLINE_API(
00198 struct timeval ast_samp2tv(unsigned int _nsamp, unsigned int _rate),
00199 {
00200    return ast_tv(_nsamp / _rate, (_nsamp % _rate) * (1000000 / (float) _rate));
00201 }
00202 )
00203 
00204 #endif /* _ASTERISK_TIME_H */

Generated on Thu Apr 16 06:28:01 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6