00001 /*! \file kogmo_time.h 00002 * \brief Definition of Time Handling Types and Functions (C-Interface) 00003 * 00004 * Copyright (c) 2005,2006 Matthias Goebl <matthias.goebl*goebl.net> 00005 * Lehrstuhl fuer Realzeit-Computersysteme (RCS) 00006 * Technische Universitaet Muenchen (TUM) 00007 */ 00008 00009 /*! \defgroup kogmo_time C-Functions for Time Handling 00010 * \brief Types and Functions for Time Handling in Cognitive Automobiles. 00011 */ 00012 /*@{*/ 00013 00014 // In this piece of source code, I tried to follow the GNU Coding Standards, 00015 // see http://www.gnu.org/prep/standards/standards.html 00016 // This file could also be used as a reference for doxygen use. 00017 00018 00019 #ifndef KOGMO_TIME_H 00020 #define KOGMO_TIME_H 00021 00022 #include <inttypes.h> /* int64_t */ 00023 00024 #ifdef __cplusplus 00025 namespace KogniMobil { 00026 extern "C" { 00027 #define _const const //!< constant argument for inclusion in C++ 00028 #else /* no C++ */ 00029 #define _const //!< constant argument, but irrelevant in C 00030 #endif 00031 00032 00033 00034 /*! \brief Absolute Timestamp (in Ticks since the "Epoch"). 00035 * 00036 * This is the reference type that to be used for all timestamps. \n 00037 * It can represent points in time from the year 1970 until 2262 00038 * with a nanosecond resolution. 00039 * 00040 * Background:\n\n 00041 * 00042 * The Epoch starts 00:00:00 UTC, January 1, 1970, see also 00043 * (POSIX.1 and time(2), http://de.wikipedia.org/wiki/Epoch). \n 00044 * This is a signed 64-Bit value that will overflow in the year 2262. \n 00045 * ( 2^63/1000000000/60/60/24/365 = 292.471.. ) 00046 * 00047 * Why a 64-Bit value value? Aren't 32 Bits enough?\n 00048 * A 32-Bit (unsigned) value would overflow after 00049 * - less than 5 seconds with a nanosecond resolution 00050 * ( 2^32/1000/1000/10e00=4.294... ) 00051 * - less than 2 hours with a microsecond resolution 00052 * ( 2^32/1000/60/60/1000=1.193... ) 00053 * - less than 50 days with millisecond resolution 00054 * ( 2^32/1000/60/60/24 = 49.710.. ) 00055 * 00056 * So only a millisecond granularity would be usefull, but 00057 * - we can use it only for a relative time with a defined 00058 * begin (e.g. system boot) 00059 * - We have to remember this start time (and possibly 00060 * save it in out logs, maybe communicate it to other vehicles) 00061 * - We wouldn't win a "Around the World in Eighty Days" race ;-) 00062 * 00063 * So please 00064 * - use this timestamp type 00065 * - get the timestamp via kogmo_timestamp_now() 00066 * - work with the timestamps using kogmo_timestamp_difference_in_seconds() 00067 * and kogmo_timestamp_add_seconds() 00068 * - use KOGMO_TIMESTAMP_TICKSPERSECOND just for your information 00069 * - DO NOT implement own calculations with nanoseconds 00070 * 00071 * There are convenience functions with float-times in seconds, 00072 * these can also be used in calculations.\n 00073 * For exchanging times you should use kogmo_time_t. 00074 * 00075 * For any questions, please contact me! 00076 * Matthias Goebl <matthias.goebl*goebl.net> 00077 */ 00078 typedef int64_t kogmo_timestamp_t; 00079 00080 00081 /*! \brief Ticks per Second. 00082 * Value, by which the result from kogmo_timestamp_now() will be incremented 00083 * every second. 00084 * 00085 * As we use Nanoseconds, its equal to 1000000000. \n 00086 * But *PLEASE* dont hardcode 1000000000 anywere, use this constant if necessary!\n 00087 * Better use the following functions to handle timestamps. 00088 */ 00089 #define KOGMO_TIMESTAMP_TICKSPERSECOND 1000000000 00090 #define KOGMO_TIMESTAMP_NANOSECONDSPERTICK (1000000000/KOGMO_TIMESTAMP_TICKSPERSECOND) 00091 00092 00093 /*! \brief Get absolute Timestamp for current Time. 00094 * \returns zero on errors 00095 */ 00096 kogmo_timestamp_t 00097 kogmo_timestamp_now (void); 00098 00099 00100 /*! \brief Calcute difference between two Timestamps (in Nanoseconds). 00101 * 00102 * \param ts_begin First Timestamp, begin of the interval 00103 * \param ts_end Second Timestamp, end of the interval 00104 * \returns Length of the interval in nanoseconds (64-Bit integer value) 00105 */ 00106 int64_t 00107 kogmo_timestamp_diff_ns (kogmo_timestamp_t ts_begin, 00108 kogmo_timestamp_t ts_end); 00109 00110 00111 /*! \brief Calcute difference between two Timestamps (in Seconds, floating point). 00112 * 00113 * This may simplify your calculations.\n 00114 * For exchanging timestamps you should use kogmo_timestamp_t instead. 00115 * 00116 * \param ts_begin First Timestamp, begin of the interval 00117 * \param ts_end Second Timestamp, end of the interval 00118 * \returns Length of the interval in Seconds (floating point value) 00119 */ 00120 double 00121 kogmo_timestamp_diff_secs (kogmo_timestamp_t ts_begin, 00122 kogmo_timestamp_t ts_end); 00123 00124 00125 /*! \brief Add time offset to Timestamps (in Nanoseconds). 00126 * 00127 * \param ts Timestamp 00128 * \param ns Nanoseconds to add, can be negative (64-Bit integer value) 00129 * \returns New Timestamp 00130 */ 00131 kogmo_timestamp_t 00132 kogmo_timestamp_add_ns (kogmo_timestamp_t ts, int64_t ns); 00133 00134 00135 /*! \brief Add time offset to Timestamps (in Seconds, floating point). 00136 * 00137 * \param ts Timestamp 00138 * \param secs Seconds to add, can be negative (floating point value) 00139 * \returns New Timestamp 00140 */ 00141 kogmo_timestamp_t 00142 kogmo_timestamp_add_secs (kogmo_timestamp_t ts, double secs); 00143 00144 00145 /*! \brief Length of the Output of kogmo_timestamp_to_string() 00146 */ 00147 #define KOGMO_TIMESTAMP_STRINGLENGTH 30 00148 00149 /*! \brief Type of a pre-allocated String to receive the Output of 00150 * kogmo_timestamp_to_string() 00151 */ 00152 typedef char kogmo_timestamp_string_t[KOGMO_TIMESTAMP_STRINGLENGTH]; 00153 00154 00155 /*! \brief Convert an Absolute Timestamp to a String, 00156 * formated according to the ISO-Standard. 00157 * 00158 * Format: 2006-04-26 23:54:27.832241000 (YYYY-MM-DD hh:mm:ss.sssssssss) 00159 * \param ts Timestamp 00160 * \param str Pre-Allocated String for the Output 00161 * \returns non-zero on errors 00162 * 00163 * The format follows ISO 8601 "Data elements and interchange formats, 00164 * Information interchange, Representation of dates and times", 00165 * with the addition of subseconds as ".sssssssss". \n 00166 * See http://en.wikipedia.org/wiki/ISO_8601 and 00167 * http://hydracen.com/dx/iso8601.htm. 00168 */ 00169 int 00170 kogmo_timestamp_to_string (kogmo_timestamp_t ts, kogmo_timestamp_string_t str); 00171 00172 00173 /*! \brief Convert an ISO-Time-String to an Absolute Timestamp. 00174 * 00175 * \param str Time as String, see kogmo_timestamp_to_string() for format 00176 * \returns Timestamp, zero on errors 00177 * 00178 * For a incomplete ISO8601-Time the missing elements will be assumed to 0.\n 00179 * For your comfort, str can also be a numeric timestamp in a string (>9999). 00180 */ 00181 kogmo_timestamp_t 00182 kogmo_timestamp_from_string (_const char *str); 00183 00184 00185 00186 #ifdef __cplusplus 00187 }; /* extern "C" */ 00188 }; /* namespace KogniMobil */ 00189 #endif 00190 00191 #endif /* KOGMO_TIME_H */ 00192 /*@}*/