Timespec structure using int64_t for its components in analogy to struct timespec_t on 64-bit platforms. More...

#include <fraction_type.hpp>

Collaboration diagram for jau::fraction_timespec:

Public Member Functions
constexpr	fraction_timespec () noexcept
	Constructs a zero fraction_timespec instance. More...

constexpr	fraction_timespec (const fraction_i64 &r, bool *overflow_ptr=nullptr) noexcept
	Conversion constructor of fraction_timespec for a fraction_i64 value. More...

constexpr	fraction_timespec (const int64_t &s, const int64_t &ns) noexcept
	Constructs a fraction_timespec instance with given components, normalized. More...

constexpr fraction_timespec &	normalize () noexcept
	Normalize tv_nsec with its absolute range [0..1'000'000'000[ or [0..1'000'000'000) and having same sign as tv_sec. More...

constexpr fraction_timespec &	operator+= (const fraction_timespec &rhs) noexcept
	Compound assignment (addition) More...

constexpr fraction_timespec &	operator-= (const fraction_timespec &rhs) noexcept
	Negative compound assignment (subtraction) More...

constexpr fraction_i64	to_fraction_i64 () const noexcept
	Returns the sum of both components. More...

std::string	to_iso8601_string () const noexcept
	Convenience string conversion interpreted since Unix Epoch in UTC to ISO 8601 `YYYY-mm-ddTHH:MM:SS.ssZ`, e.g. More...

std::string	to_string () const noexcept
	Return simple string representation in seconds and nanoseconds. More...

constexpr struct timespec	to_timespec () const noexcept
	Return conversion to POSIX `struct timespec`, potentially narrowing the components if underlying system is not using 64-bit signed integer. More...

Public Attributes
int64_t	tv_nsec
	Nanoseconds component with its absolute value in range [0..1'000'000'000[ or [0..1'000'000'000), sharing same sign with tv_nsec. More...

int64_t	tv_sec
	Seconds component, with its absolute value in range [0..inf[ or [0..inf), sharing same sign with tv_nsec. More...

Detailed Description

Timespec structure using int64_t for its components in analogy to struct timespec_t on 64-bit platforms.

fraction_timespec covers an almost infinite range of time while maintaining high precision like struct timespec_t on 64-bit platforms.

If used as an absolute time-point, zero is time since Unix Epoch 00:00:00 UTC on 1970-01-01.

Note-1: Counting nanoseconds in int64_t only lasts until 2262-04-12, since INT64_MAX is 9'223'372'036'854'775'807 for 9'223'372'036 seconds or 292 years.

Note-2: Limitations of struct timespec on 32-bit platforms

to_timespec() conversion to struct timespec
32-bit signed integer only last for 68 years or until year 2038, starting from 1970 Unix Epoch
System call conversion for year 2038
test/test_fractions_01.cpp struct timespec type validation Test 03.00

See also: to_timespec(); to_fraction_i64(); sleep_until(); sleep_for(); wait_until(); wait_for(); getMonotonicTime(); getWallClockTime()

Definition at line 869 of file fraction_type.hpp.

Constructor & Destructor Documentation

◆ fraction_timespec() [1/3]

constexpr jau::fraction_timespec::fraction_timespec ( )

inlineconstexprnoexcept

Constructs a zero fraction_timespec instance.

Definition at line 885 of file fraction_type.hpp.

◆ fraction_timespec() [2/3]

constexpr jau::fraction_timespec::fraction_timespec	(	const int64_t &	s,
		const int64_t &	ns
	)

inlineconstexprnoexcept

Constructs a fraction_timespec instance with given components, normalized.

Definition at line 891 of file fraction_type.hpp.

◆ fraction_timespec() [3/3]

constexpr jau::fraction_timespec::fraction_timespec	(	const fraction_i64 &	r,
		bool *	overflow_ptr = `nullptr`
	)

inlineconstexprnoexcept

Conversion constructor of fraction_timespec for a fraction_i64 value.

If overflow_ptr is not nullptr, true is stored if an overflow occurred, otherwise false.

In case of an overflow, tv_sec and tv_nsec will also be set to INT64_MAX

Example without overflow check and implicit fraction_i64 conversion to fraction_timespec:

 fraction_i64 duration = 10_ms;
 const fraction_timespec timeout_time = getMonotonicTime() + duration;

Example with overflow check for potential durations > 292 years and explicit fraction_i64 conversion to fraction_timespec:

 fraction_i64 duration = 10_ms;
 bool overflow = false;
 const fraction_timespec timeout_time = getMonotonicTime() + fraction_timespec(duration, &overflow);
 if( overflow ) {
     return; // bail out
 }

Parameters

r	the conversion input
overflow_ptr	optional pointer to overflow result, defaults to nullptr

Definition at line 919 of file fraction_type.hpp.

Member Function Documentation

◆ to_fraction_i64()

constexpr fraction_i64 jau::fraction_timespec::to_fraction_i64 ( ) const

inlineconstexprnoexcept

Returns the sum of both components.

If applied to relative duration, i.e. difference of two time points, its range is good for 292 years and exceeds that of an int64_t nanoseconds timepoint-difference greatly.

  fraction_timespec t0 = getMonotonicTime();
  // do something

  // Exact duration
  fraction_timespec td_1 = getMonotonicTime() - t0;

  // or for durations <= 292 years
  fraction_i64 td_2 = (getMonotonicTime() - t0).to_fraction_i64();

See also: getMonotonicTime()

Definition at line 955 of file fraction_type.hpp.

Here is the caller graph for this function:

◆ normalize()

constexpr fraction_timespec & jau::fraction_timespec::normalize ( )

inlineconstexprnoexcept

Normalize tv_nsec with its absolute range [0..1'000'000'000[ or [0..1'000'000'000) and having same sign as tv_sec.

Used after arithmetic operations.

Returns: reference to this instance

Definition at line 967 of file fraction_type.hpp.

Here is the caller graph for this function:

◆ operator+=()

constexpr fraction_timespec & jau::fraction_timespec::operator+= ( const fraction_timespec & rhs )

inlineconstexprnoexcept

Compound assignment (addition)

Parameters

rhs	the other fraction_timespec

Returns: reference to this instance, normalized

Definition at line 991 of file fraction_type.hpp.

◆ operator-=()

constexpr fraction_timespec & jau::fraction_timespec::operator-= ( const fraction_timespec & rhs )

inlineconstexprnoexcept

Negative compound assignment (subtraction)

Parameters

rhs	the other fraction_timespec

Returns: reference to this instance, normalized

Definition at line 1003 of file fraction_type.hpp.

◆ to_timespec()

constexpr struct timespec jau::fraction_timespec::to_timespec ( ) const

inlinenoexcept

Return conversion to POSIX struct timespec, potentially narrowing the components if underlying system is not using 64-bit signed integer.

Note-2: Limitations of struct timespec on 32-bit platforms

32-bit signed integer only last for 68 years or until year 2038, starting from 1970 Unix Epoch
System call conversion for year 2038
test/test_fractions_01.cpp struct timespec type validation Test 03.00

Definition at line 1018 of file fraction_type.hpp.

Here is the caller graph for this function:

◆ to_string()

std::string fraction_timespec::to_string ( ) const

noexcept

Return simple string representation in seconds and nanoseconds.

Definition at line 76 of file basic_types.cpp.

Here is the caller graph for this function:

◆ to_iso8601_string()

std::string fraction_timespec::to_iso8601_string ( ) const

noexcept

Convenience string conversion interpreted since Unix Epoch in UTC to ISO 8601 YYYY-mm-ddTHH:MM:SS.ssZ, e.g.

'2022-06-23T14:34:10Zor '2022-06-23T14:34:10.228978909Z.

Implementation uses strftime() with format Y-m-dTH:M:S and adds 9 digits nanoseconds as fractions of seconds if not zero and the final Z.

Definition at line 80 of file basic_types.cpp.

Here is the caller graph for this function:

Member Data Documentation

◆ tv_sec

int64_t jau::fraction_timespec::tv_sec

Seconds component, with its absolute value in range [0..inf[ or [0..inf), sharing same sign with tv_nsec.

Definition at line 874 of file fraction_type.hpp.

◆ tv_nsec

int64_t jau::fraction_timespec::tv_nsec

Nanoseconds component with its absolute value in range [0..1'000'000'000[ or [0..1'000'000'000), sharing same sign with tv_nsec.

Definition at line 880 of file fraction_type.hpp.

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

include/jau/fraction_type.hpp
src/basic_types.cpp

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ fraction_timespec() [1/3]

◆ fraction_timespec() [2/3]

◆ fraction_timespec() [3/3]

Member Function Documentation

◆ to_fraction_i64()

◆ normalize()

◆ operator+=()

◆ operator-=()

◆ to_timespec()

◆ to_string()

◆ to_iso8601_string()

Member Data Documentation

◆ tv_sec

◆ tv_nsec