| # Gaudi Framework, version v20r2
Generated: 18 Jul 2008

- Main Page
- Namespaces
- Classes
- Files
- Directories
- Related Pages

- Search for |

- Alphabetical List
- Class List
- Class Hierarchy
- Class Members

# Gaudi::Time Class Reference

`#include <GaudiKernel/Time.h>`

Collaboration diagram for Gaudi::Time:

[legend]
List of all members.

## Detailed Description

Based on seal::Time.

Calendar time in nanoseconds since 00:00:00 on January 1, 1970, Coordinated Universal Time (UTC).

Time is represented internally as UTC time, but it can also be converted to the local time as necessary. Most methods take an argument flag `local` to indicate which time interpretation is desired by the client, and automatically perform the necessary adjustments. The client can also find out about the difference between UTC time and local time using the utcoffset() method, and the time zone name with timezone() method. Both allow the client to discover whether daylight savings is in effect.

The native representation of Time is not well suited for human handling of time. Time provides access in more convenient terms such as year(), month() and day(); more are available through conversion into a TimeSpan. Time can also be converted to and from ISO C standard `tm` structure. Note however that unlike C's `mktime()` which always assumes `tm` in local time, Time fully supports all conversions between local and universal time. Thus it is possible for example to build() a UTC time directly from a `tm`.

Time behaves as an integral type. Differences in time values are represented as a TimeSpan. Usual integral arithmetic works with both types. Output works in general as any other integral type, however since the ValueType can be a wide type, it may be poorly supported by the `iostream`; if so, including the `LongLong.h` header will help. Note that the output value will usually be very large as Time is represented in nanoseconds, not seconds! When constructing Time values in seconds, such as when reading in, do remember to use the two-argument constructor taking seconds and nanoseconds instead of the default single-argument one.

Time can be formatted into a string using the format() method, which uses the versatile `strftime()` function. Since the latter works on seconds at best (through a struct `tm`), the subsecond part cannot be formatted; the nanoformat() method is provided to overcome this limitation. To combine format() and nanoformat() output use a suitable StringFormat pattern.

Time is linked to the system's concept of calendar time and is therefore may not be linear nor monotonic. System time can jump arbitrarily in either direction as real time clock is corrected or the system is suspended. The local time may also jump due to daylight savings. The process' ability to sample system time can be limited for reasons such as getting swapped out. TimeInfo provides an alternative time measurement facility not linked to calendar and guaranteed to grow monotonically -- though not always linearly. Note that few systems actually provide wall-clock time in nanosecond resolution. Not all system provide an interface to get time at that resolution, let alone track it so precisely.

Because of the time warp issues, scheduling events using Time is not straightforward. Application code should understand whether it is dealing with concrete or abstract calendar calculations, and how the events it schedules are linked to wall clock time.

For calculations on concrete calendar as perceived by people use local() after plain Time and TimeSpan integer arithmetic. The method accounts for timezone and daylight savings definitions. To schedule events use build() to derive times from local() time to get values comparable to the system time returned by current(). The applications should know whether events are scheduled in UTC or local time---"meeting at 9:00 on Wednesday morning" when the device switches timezones may be known to be at 9:00 in the new timezone (= locked to local time), or in the timezone where the event was created (= locked to UTC). The build() and split() methods allow either format to be used, the application just needs to know which one to use. It is also easy to convert between the two using utcoffset().

For calculations using an abstract calendar, without timezone or daylight savings, use Time in its native UTC representation and integer arithmetic with Time and TimeSpan. Do note however that "T + 24 hours" may not be the same hour the next day in the local calendar time -- timezone changes and daylight savings make a difference. This may require the application to accept as user input exception rules to its usual calendar calculations.

To schedule events, one should choose between three choices: UTC time, local time, or delta time. For the first two cases system time should be polled regularly to see if any of the recorded events have expired. It is not a good idea to sleep until the next scheduled event, as the system time may jump during the nap; instead sleep small increments, recheck the current time after each nap and trigger the events that have expired. A policy must be applied when the system time warps; this can happen both forwards and backwards with both local and UTC time (daylight savings or timezone changes for mobile devices are common local time change reasons, but the system time can be updated for any reason, e.g. when the real time clock is wrong, or if the system is suspended for a long time). Some events should be executed only once in case of time warps backwards. If the time jumps forwards, several events may need to be dealt with in one go. In either case the application should guard against major time changes: long system suspends, moving mobile devices and major time updates may result in a large number of "missed" events. One possibility is to provide a user-configurable "excessive time drift limit" (e.g. N hours): if time changes by more than that, missed events are not triggered.

For the final case of using delta times, sort upcoming events by their deltas from the previous event---not by the time they are anticipated to occur. Capture current time before and after the sleep and pull events off the queue based on the difference (the sleep time may exceed the requested time). Either guard against long time warps like suspends or schedule timer events cautiously. Using TimeInfo as schedule base solves such issues simply. To cope with backward system time jumps when using Time as schedule base, assume that sleeps always last at least the requested time; if the time delta over the nap is less than the requested, assume time warp (this is not foolproof against interrupted system calls but works for many event scheduling situations).

See also:
  TimeInfo for monotonic time not related to the calendar. (Documentation taken from original SEAL class)

Author:
  Marco Clemencic

Date:
  2005-12-15

Definition at line 216 of file Time.h.

## Public Types
enum | Months { January = 0, February = 1, March = 2, April = 3, May = 4, June = 5, July = 6, August = 7, September = 8, October = 9, November = 10, December = 11 }
| Symbolic names for months. More...
typedef longlong | ValueType
## Public Member Functions
| Time (void)
| Initialize an empty (zero) time value.
| Time (TimeSpan ts)
| Initialize time to ts nanoseconds since 00:00:00 on January 1, 1970 in UTC.
| Time (ValueType nsecs)
| Initialize time to nsecs nanoseconds since 00:00:00 on January 1, 1970 in UTC.
| Time (ValueType secs, int nsecs)
| Initialize time to secs (seconds) and nsecs (nanoseconds) summed since 00:00:00 on January 1, 1970 in UTC.
| Time (int year, int month, int day, int hour, int min, int sec, ValueType nsecs, bool local=true)
tm | split (bool local, int *nsecpart=0) const
tm | utc (int *nsecpart=0) const
tm | local (int *nsecpart=0) const
int | year (bool local) const
int | month (bool local) const
int | day (bool local) const
int | hour (bool local) const
int | minute (bool local) const
int | second (bool local) const
int | nsecond (void) const
int | weekday (bool local) const
bool | isdst (bool local) const
ValueType | utcoffset (int *daylight=0) const
const char * | timezone (int *daylight=0) const
Time & | operator+= (const TimeSpan &x)
| Add the specified amount to the time.
Time & | operator-= (const TimeSpan &x)
| Subtract the specified amount from the time.
ValueType | ns (void) const
| Return the time as nanoseconds since 00:00:00 on January 1, 1970 in UTC.
std::string | format (bool local, const std::string &spec) const
std::string | nanoformat (int minwidth=1, int maxwidth=9) const
## Static Public Member Functions
static Time | epoch (void)
| Return the time for the epoch (= zero time).
static Time | max (void)
| Return the maximum time.
static Time | current (void)
| Returns the current time.
static Time | build (bool local, const tm &base, TimeSpan diff=0)
static bool | isLeap (int year)
| Check if the year is a leap-year.
static unsigned | toDosDate (Time time)
static Time | fromDosDate (unsigned dosDate)
## Static Public Attributes
static const int | SECS_PER_DAY = 86400
| Seconds in 24 hours.
static const int | SECS_PER_HOUR = 3600
| Seconds in one hour hour.
static const ValueType | SEC_NSECS = 1000000000
| Nanoseconds in one second.
## Private Member Functions
void | TimeAssert (bool cond, const std::string &msg="time assertion failed") const
## Private Attributes
ValueType | m_nsecs
## Friends
class | TimeSpan

## Member Typedef Documentation

typedef longlong Gaudi::Time::ValueType

Definition at line 219 of file Time.h.

## Member Enumeration Documentation

enum Gaudi::Time::Months

Symbolic names for months.

Enumerator:

  January |
  February |
  March |
  April |
  May |
  June |
  July |
  August |
  September |
  October |
  November |
  December |

Definition at line 222 of file Time.h.

    00222                 {
    00223       January  = 0,
    00224       February = 1,
    00225       March  = 2,
    00226       April  = 3,
    00227       May  = 4,
    00228       June  = 5,
    00229       July  = 6,
    00230       August  = 7,
    00231       September = 8,
    00232       October  = 9,
    00233       November = 10,
    00234       December = 11
    00235     };

## Constructor & Destructor Documentation

Gaudi::Time::Time | ( | void |  | ) | `[inline]`

Initialize an empty (zero) time value.

Definition at line 10 of file Time.icpp.

    00010 : m_nsecs(0) {}

Gaudi::Time::Time | ( | TimeSpan | ts | ) | `[inline]`

Initialize time to ts nanoseconds since 00:00:00 on January 1, 1970 in UTC.

Definition at line 20 of file Time.icpp.

References m_nsecs, and TimeAssert().

    00020                                 : m_nsecs(ts.m_nsecs) {
    00021     TimeAssert( m_nsecs >= 0, "cannot create a negative time");
    00022   }

Gaudi::Time::Time | ( | ValueType | nsecs | ) | `[inline]`

Initialize time to nsecs nanoseconds since 00:00:00 on January 1, 1970 in UTC.

Definition at line 14 of file Time.icpp.

References m_nsecs, and TimeAssert().

    00014                                    : m_nsecs(nsecs) {
    00015     TimeAssert( m_nsecs >= 0, "cannot create a negative time");
    00016   }

Gaudi::Time::Time | ( | ValueType | secs,
|  | int | nsecs |
| ) |  |  | `[inline]`

Initialize time to secs (seconds) and nsecs (nanoseconds) summed since 00:00:00 on January 1, 1970 in UTC.

Definition at line 26 of file Time.icpp.

References m_nsecs, and TimeAssert().

    00027     : m_nsecs(secs * Time::SEC_NSECS + nsecs) {
    00028     TimeAssert( m_nsecs >= 0, "cannot create a negative time");
    00029   }

Gaudi::Time::Time | ( | int | year,
|  | int | month,
|  | int | day,
|  | int | hour,
|  | int | min,
|  | int | sec,
|  | ValueType | nsecs,
|  | bool | local = `true` |
| ) |  |  |

## Member Function Documentation

Time Gaudi::Time::epoch | ( | void |  | ) | `[inline, static]`

Return the time for the epoch (= zero time).

Definition at line 54 of file Time.icpp.

    00054                                {
    00055     return 0LL;
    00056   }

Time Gaudi::Time::max | ( | void |  | ) | `[inline, static]`

Return the maximum time.

Definition at line 59 of file Time.icpp.

    00059                              {
    00060     return 0x7fffffffffffffffLL;
    00061   }

static Time Gaudi::Time::current | ( | void |  | ) | `[static]`

Returns the current time.

static Time Gaudi::Time::build | ( | bool | local,
|  | const tm & | base,
|  | TimeSpan | diff = `0` |
| ) |  |  | `[static]`

tm Gaudi::Time::split | ( | bool | local,
|  | int * | nsecpart = `0` |
| ) |  |  | const

tm Gaudi::Time::utc | ( | int * | nsecpart = `0` | ) | const

tm Gaudi::Time::local | ( | int * | nsecpart = `0` | ) | const

int Gaudi::Time::year | ( | bool | local | ) | const

int Gaudi::Time::month | ( | bool | local | ) | const

int Gaudi::Time::day | ( | bool | local | ) | const

int Gaudi::Time::hour | ( | bool | local | ) | const

int Gaudi::Time::minute | ( | bool | local | ) | const

int Gaudi::Time::second | ( | bool | local | ) | const

int Gaudi::Time::nsecond | ( | void |  | ) | const

int Gaudi::Time::weekday | ( | bool | local | ) | const

bool Gaudi::Time::isdst | ( | bool | local | ) | const

ValueType Gaudi::Time::utcoffset | ( | int * | daylight = `0` | ) | const

const char* Gaudi::Time::timezone | ( | int * | daylight = `0` | ) | const

Time & Gaudi::Time::operator+= | ( | const TimeSpan & | x | ) | `[inline]`

Add the specified amount to the time.

Note that Time is always expressed in UTC.

Definition at line 39 of file Time.icpp.

References Gaudi::TimeSpan::m_nsecs, m_nsecs, and TimeAssert().

    00039                                                   {
    00040     TimeAssert( m_nsecs >= -x.m_nsecs, "time operation lead to negative time");
    00041     m_nsecs += x.m_nsecs;
    00042     return *this;
    00043   }

Time & Gaudi::Time::operator-= | ( | const TimeSpan & | x | ) | `[inline]`

Subtract the specified amount from the time.

Note that Time is always expressed in UTC.

Definition at line 47 of file Time.icpp.

References Gaudi::TimeSpan::m_nsecs, m_nsecs, and TimeAssert().

    00047                                                   {
    00048     TimeAssert( m_nsecs >= x.m_nsecs, "time operation lead to negative time");
    00049     m_nsecs -= x.m_nsecs;
    00050     return *this;
    00051   }

Time::ValueType Gaudi::Time::ns | ( | void |  | ) | const`[inline]`

Return the time as nanoseconds since 00:00:00 on January 1, 1970 in UTC.

Definition at line 33 of file Time.icpp.

References m_nsecs.

    00033                                            {
    00034     return m_nsecs;
    00035   }

std::string Gaudi::Time::format | ( | bool | local,
|  | const std::string & | spec |
| ) |  |  | const

std::string Gaudi::Time::nanoformat | ( | int | minwidth = `1`,
|  | int | maxwidth = `9` |
| ) |  |  | const

bool Gaudi::Time::isLeap | ( | int | year | ) | `[inline, static]`

Check if the year is a leap-year.

Definition at line 64 of file Time.icpp.

    00064                                     {
    00065     return ((year % 4) == 0
    00066             && ((year % 100) != 0
    00067                 || (year % 400) == 0));
    00068   }

static unsigned Gaudi::Time::toDosDate | ( | Time | time | ) | `[static]`

static Time Gaudi::Time::fromDosDate | ( | unsigned | dosDate | ) | `[static]`

void Gaudi::Time::TimeAssert | ( | bool | cond,
|  | const std::string & | msg = `"time assertion failed"` |
| ) |  |  | const`[inline, private]`

Definition at line 301 of file Time.h.

References TimeAssert().

Referenced by operator+=(), operator-=(), Time(), and TimeAssert().

    00301                                                                                             {
    00302       if (!cond) throw TimeException(msg);
    00303     }

## Friends And Related Function Documentation

friend class TimeSpan`[friend]`

Definition at line 217 of file Time.h.

## Member Data Documentation

const int Gaudi::Time::SECS_PER_DAY = 86400`[static]`

Seconds in 24 hours.

Definition at line 238 of file Time.h.

const int Gaudi::Time::SECS_PER_HOUR = 3600`[static]`

Seconds in one hour hour.

Definition at line 241 of file Time.h.

const ValueType Gaudi::Time::SEC_NSECS = 1000000000`[static]`

Nanoseconds in one second.

Definition at line 244 of file Time.h.

ValueType Gaudi::Time::m_nsecs`[private]`

Definition at line 299 of file Time.h.

Referenced by ns(), operator+=(), operator-=(), and Time().

The documentation for this class was generated from the following files:

- /afs/cern.ch/sw/Gaudi/releases/GAUDI/GAUDI_v20r2/GaudiKernel/v25r2/GaudiKernel/Time.h
- /afs/cern.ch/sw/Gaudi/releases/GAUDI/GAUDI_v20r2/GaudiKernel/v25r2/GaudiKernel/Time.icpp