Time Representation

fort::Duration

class Duration

The amount of time ellapsed between two Time.

A Duration represents the amount of time between two Time.

This class aims to replicate a go syntax. For example to represent one hour, 10 minute, one may write:

 {c++}
using namespace fort;
Duration d = 1 * Duration::Hour + 10 * Duration::Minute;

Public Functions

inline Duration(int64_t ns)

constructor by an ammount of nanosecond

Parameters:

ns – the number of nanosecond

inline Duration()

Default constructor with a zero duration.

template<typename T, typename U>
inline Duration(const std::chrono::duration<T, U> &duration)

constructor from std::chrono::duration

Template Parameters:

• T – first <std::chrono::duration> template

• U – second <std::chrono::duration> template

Parameters:

duration – the <std::chrono::duration> to convert

double Hours() const

Gets the duration in hours.

Returns:

the duration in hours

double Minutes() const

Gets the duration in minutes.

Returns:

the duration in minutes

double Seconds() const

Gets the duration in seconds.

Returns:

the duration in seconds

double Milliseconds() const

Gets the duration in milliseconds.

Returns:

the duration in milliseconds

double Microseconds() const

Gets the duration in microseconds.

Returns:

the duration in microseconds

inline int64_t Nanoseconds() const

Gets the duration in nanoseconds.

Returns:

the duration in nanoseconds

inline Duration operator+(const Duration &other) const

The addition operator.

Adds two Duration. Silently overflow following int64_t arithmetic.

Parameters:

other – the other Duration to add

Returns:

a new duration this + other

inline Duration operator*(const fort::Duration &other) const

Multiplication operator.

Multiplies two Duration.

Parameters:

other – the other Duration to multiply.

Returns:

a new duration this * other

inline Duration operator-(const fort::Duration &other) const

Substraction operator.

Substracts two Duration.

Parameters:

other – the other Duration to substract

Returns:

a new duration this - other

inline Duration operator-() const

Negation operator.

Returns:

the opposite duration - this

inline bool operator<(const Duration &other) const

Less than operator.

Compares two Duration.

Parameters:

other – the Duration to compare

Returns:

this < other

inline bool operator<=(const Duration &other) const

Less or equal operator.

Compares two Duration.

Parameters:

other – the Duration to compare

Returns:

this <= other

inline bool operator>(const Duration &other) const

Greater than operator.

Compares two Duration.

Parameters:

other – the Duration to compare

Returns:

this > other

inline bool operator>=(const Duration &other) const

Greater or equal operator.

Compares two Duration.

Parameters:

other – the Duration to compare

Returns:

this >= other

inline bool operator==(const Duration &other) const

Equality operator.

Compares two Duration.

Parameters:

other – the Duration to compare

Returns:

this == other

Public Static Functions

static Duration Parse(const std::string &d)

Parses a string to a Duration.

Parses a std::string to a Duration. string must be of the form [amount][unit] where [amount] is a value that may contain a decimal point, and [unit] could be any of h, m, s, ms, us, µs and ns. This pattern may be repeated. For example 4m32s is a valid input.

Parameters:

d – the string to Parse in the form "2h" or "1m"

Throws:

std::runtime_error – if d is an invalid string

Returns:

the Duration represented by the string.

Public Static Attributes

static const Duration Hour

The Value for an hour.

static const Duration Minute

The Value for a minute.

static const Duration Second

The Value for a second.

static const Duration Millisecond

The Value for a millisecond.

static const Duration Microsecond

The Value for a microsecond.

static const Duration Nanosecond

The Value for a nanosecond.

fort::Time

class Time

A point in time.

Time represents a point in time in UTC timezone

why not std::chrono::time_point ?

Why re-implementing one of this object and not using a struct timeval or a std::chrono ? We are dealing with long living experiment on heterogenous systems. Under this circunstances, we would like also to measure precise time difference. For this purpose we could use the framegrabber monolotic clock, which is timestamping every frame we acquired.

Well the issue is that we cannot solely rely on this clock, as we may have several computers each with their own monolithic clock. Or even with a single computer, every time we starts the tracking we must assume a new monotonic clock.

We could use the wall clock but this clock may be resetted any time, and we would end up with issue where a time difference between two consecutive frames could be negative. This happen during leap seconds.

Inspired from golang time.Time we propose an Object that store both a Wall time, and a Monotonic timestamp. But here we could have different monotonic timestamp issued by different monotonic clocks. We try, whenever its possible use monotonic value for time differences and comparisons. It could only be the case if both object have a MonotonicValue() issued from the same clock. Otherwise the Wall clock value will be used with the issue regarding the jitter or Wall clock reset.

Differentiaing Monotonic clock is done through MonoclockID() values. The 0 value is reserved for the SYSTEM_MONOTONIC_CLOCK and which is used by Now(). When reading saved monotonic Timestamp from the filesystem (as it is the case when reading data from different TrackingDataDirectory ), care must be taken to assign different MonoclockID() for each of those reading. This class does not enforce any mechanism. The only entry point to define the MonoclockID() is through the utility function FromTimestampAndMonotonic().

Every time are considered UTC.

Public Types

typedef uint32_t MonoclockID

ID for a Monotonic Clock.

Public Functions

time_t ToTimeT() const

Converts to a time_t

Returns:

time_trepresenting the Time.

timeval ToTimeval() const

Converts to a struct timeval

Returns:

struct timevalrepresenting the Time.

google::protobuf::Timestamp ToTimestamp() const

Converts to a protobuf Timestamp message.

Returns:

the protobuf Timestamp representing the Time.

void ToTimestamp(google::protobuf::Timestamp *timestamp) const

In-place conversion to a protobuf Timestamp.

Parameters:

timestamp – the timestamp to modify to represent the Time

explicit Time()

Default constructor to the system’s epoch.

The resulting Time will represent the epoch.

Time Add(const Duration &d) const

Adds a Duration to a Time.

Parameters:

d – the Duration to add

Throws:

Overflow – if the computation will go over the minimal or maximal representable Time.

Returns:

a new Time distant by d from this Time

Time Round(const Duration &d) const

Rounds a Time to a Duration.

Rounds the Time to the half-rounded up Duration d. Currently only multiple of Duration::Second and power of 10 of Duration::Nanosecond which are smaller than a second are supported.

Parameters:

d – the Duration to round to.

Returns:

a new Time rounded to the wanted duration

Duration Reminder(const Duration &d) const

Gets the Reminder of the division by a Duration.

Finds the Duration which remains if this Time would be divided by d. Only multiple of Duration::Second or power of 10 of Duration::Nanosecond smaller than a second are supported.

Parameters:

d – the Duration to divide by

Returns:

a Duration that would remain if this Time would be divided by d

bool After(const Time &t) const

Reports if this time is after t.

Parameters:

t – the Time to test against

Returns:

true if this Time is strictly after t

bool Before(const Time &t) const

Reports if this time is before t.

Parameters:

t – the Time to test against

Returns:

true if this Time is strictly before t

bool Equals(const Time &t) const

Reports if this time is the same than t * * Python:

Parameters:

t – the Time to test against

Returns:

true if this Time> is the same than t

bool IsForever() const

Reports if this Time is +∞

Returns:

true if this Time is Forever()

bool IsSinceEver() const

Reports if this Time is -∞

Returns:

true if this Time is SinceEver()

bool IsInfinite() const

Reports if this Time is either Forever or SinceEver.

Returns:

true if this Time is Forever() or SinceEver().

Duration Sub(const Time &t) const

Computes time difference with another time.

Parameters:

t – the Time to substract to this one.

Throws:

Overflow – if the time Differance is larger than a signed 64-bit amount of nanoseconds.

Returns:

a Duration representing the time ellapsed between this and t. It could be negative.

bool HasMono() const

Reports the presence of a monotonic time value.

Reports the presence of a monotonic time value. Only Time issued by Now() or FromTimestampAndMonotonic() contains a monotonic time value.

Returns:

true if this contains a monotonic clock value.

MonoclockID MonoID() const

Gets the referred MonoclockID.

Throws:

std::exception – if this Time has no monotonic clock value.

Returns:

the MonoclockID designating the monotonic clock the monotonic time value refers to.

uint64_t MonotonicValue() const

Gets the monotonic value.

Throws:

std::exception – if this Time has no monotonic clock value.

Returns:

the monotonic clock value.

std::string Format() const

Formats the Time as a RFC 3339 string.

Returns:

a string representing this Time. Either using RFC 3339 or +/-∞ if this Time::IsInfinite()

std::string DebugString() const

Builds a debug string.

This method is useful for internal debugging. Prefer the standard c++ formatting operator on std::ostream or Format().

Returns:

a debug string with the complete time internal state.

inline bool operator==(const Time &other) const

Equal comparison operator.

Parameters:

other – the other Time to compare to

Returns:

true if this == other

inline bool operator<(const Time &other) const

Less than operator.

Parameters:

other – the other Time to compare to

Returns:

true if this < other

inline bool operator<=(const Time &other) const

Less or equal operator.

Parameters:

other – the other Time to compare to

Returns:

true if this <= other

inline bool operator>(const Time &other) const

Greater than operator.

Parameters:

other – the other Time to compare to

Returns:

true if this > other

inline bool operator>=(const Time &other) const

Greate or equal operator.

Parameters:

other – the other Time to compare to

Returns:

true if this >= other

Public Static Functions

static Time Forever()

Returns the positive infinite Time.

Returns the positive infinite Time. For any other Time value, Before() will return true. Any computation with this value will Overflow. Calling this method is the only to construct such Time, as operation on other regular Time will Overflow before.

Returns:

a positive infinite Time

static Time SinceEver()

Returns the negative infinite Time.

Returns the negative infinite Time. For any other Time value, After() will return true. Any computation with this value will Overflow. Calling this method is the only to construct such Time, as operation on other regular Time will Overflow before.

Returns:

a negative infinite Time

static Time Now()

Gets the current Time.

Gets the current Time. This time will both have a wall and a monotonic clock reading associated with the SYSTEM_MONOTONIC_CLOCK. Therefore such idioms:

 {c++}
auto start = fort::Time::Now();
SomeFunction();
auto ellapsed = fort::Time::Now().Sub(start);

Will always return a positive Duration, even if the wall clock has been reset between the two calls to Now()

Returns:

the current <myrmidon::Time>

static Time FromTimeT(time_t t)

Creates a Time from time_t

The Time will not have any monotonic clock value.

Parameters:

t – the time_t value

Returns:

the converted Time

static Time FromTimeval(const timeval &t)

Creates a Time from struct timeval

The Time will not have any monotonic clock value.

Parameters:

t – the struct timeval

Returns:

the converted Time

static Time FromTimestamp(const google::protobuf::Timestamp &timestamp)

Creates a Time from a protobuf Timestamp.

The Time will not have any monotonic clock value.

Parameters:

timestamp – the google.protobuf.Timestamp message

Returns:

the converted Time

static Time FromUnix(int64_t seconds, int32_t nanoseconds)

Creates a Time from Unix EPOCH.

Parameters:

• seconds – number of seconds since 1970-01-01T00:00:00.000Z

• nanoseconds – reminder of seconds since 1970-01-01T00:00:00.000Z

Returns:

the corresponding Time

static Time FromTimestampAndMonotonic(const google::protobuf::Timestamp &timestamp, uint64_t nsecs, MonoclockID monoID)

Creates a Time from a protobuf Timestamp and an external Monotonic clock.

Creates a Time from a protobuf Timestamp and an external monotonic clock. The two values should correspond to the same physical time. It is an helper function to create accurate Time from data saved in fort.hermes.FrameReadout protobuf messages that saves both a Wall time value and a framegrabber timestamp for each frame. It is the caller responsability to manage monoID values for not mixing timestamp issued from different clocks. Nothing prevent you to use SYSTEM_MONOTONIC_CLOCK for the monoID value but the behavior manipulating resulting times is undefined.

Parameters:

• timestamp – the google.protobuf.Timestamp message

• nsecs – the external monotonic value in nanoseconds

• monoID – the external monoID

Returns:

the converted Time with associated monotonic data

static Time Parse(const std::string &input)

Parses from RFC 3339 date string format.

Parses from RFC 3339 date string format, i.e. string of the form 1972-01-01T10:00:20.021-05:00. It is merely a wrapper from google::protobuf::time_util functions.

Parameters:

input – the string to parse

Throws:

std::exception – if input is not a RFC 3339 valid string

Returns:

the converted <myrmidon::Time>

static uint64_t MonoFromSecNSec(uint64_t sec, uint64_t nsec)

Helpers to convert (sec,nsec) to nsec.

Parameters:

• sec – the amount of second

• nsec – the amount of nanos

Throws:

Overflow –

Returns:

sec * 1e9 + nsec if no overflow

Public Static Attributes

static const MonoclockID SYSTEM_MONOTONIC_CLOCK = 0

The current system monotonic clock.

The MonoclockID reserved for the current system ( aka CLOCK_MONOTONIC).

class Overflow : public runtime_error

Time values can overflow when performing operation on them.

Public Functions

inline Overflow(const std::string &clocktype)

Construct an overflow from a clocktype name.

Parameters:

clocktype – the clock type to use

inline virtual ~Overflow()

default destructor