micro_os_plus::micro_test_plus::detail::timestamps Class Reference

A begin/end timestamp pair used to measure elapsed time. More...

#include <micro-os-plus/micro-test-plus.h>

Public Member Functions
	timestamps ()=default
	Default constructor. Both timestamps are uninitialised.
	timestamps (const timestamps &)=delete
	Deleted copy constructor to prevent copying.
	timestamps (timestamps &&)=delete
	Deleted move constructor to prevent moving.
	~timestamps ()=default
	Defaulted destructor.
void	compute_elapsed_time (uint32_t &milliseconds, uint32_t &microseconds) const
	Computes the elapsed time between begin and end timestamps.
bool	has_begin () const noexcept
	Returns true if the begin timestamp has been recorded.
bool	has_end () const noexcept
	Returns true if the end timestamp has been recorded.
bool	has_timestamps (void) const noexcept
	Returns true if both begin and end timestamps are available.
timestamps &	operator= (const timestamps &)=delete
	Deleted copy assignment operator to prevent copying.
timestamps &	operator= (timestamps &&)=delete
	Deleted move assignment operator to prevent moving.
void	timestamp_begin (const timespec &ts) noexcept
	Records the begin timestamp from a caller-supplied value.
void	timestamp_begin (void) noexcept
	Records the begin timestamp using the current system clock.
void	timestamp_end (const timespec &ts) noexcept
	Records the end timestamp from a caller-supplied value.
void	timestamp_end (void) noexcept
	Records the end timestamp using the current system clock.

Protected Attributes
std::optional< timestamp >	begin_time_
	The timestamp recorded at the beginning of the test suite.
std::optional< timestamp >	end_time_
	The timestamp recorded at the end of the test suite.

Detailed Description

timestamps stores an optional begin timestamp and an optional end timestamp. When both are available, compute_elapsed_time() derives the elapsed interval in milliseconds and microseconds.

Typical usage in the framework:

1. Call timestamp_begin() just before the test suite or session body executes.
2. Call timestamp_end() immediately after it completes.
3. Pass the elapsed values to the reporter.

If the platform does not provide a monotonic clock, the std::optional members remain empty and has_timestamps() returns false, so that the reporter can skip timing output.

The class is non-copyable and non-movable to prevent accidental sharing of live timing state.

Definition at line 204 of file timings.h.

Constructor & Destructor Documentation

timestamps() [1/3]

micro_os_plus::micro_test_plus::detail::timestamps::timestamps ( )

default

Referenced by timestamps(), timestamps(), operator=(), and operator=().

timestamps() [2/3]

micro_os_plus::micro_test_plus::detail::timestamps::timestamps ( const timestamps & )

delete

References timestamps().

timestamps() [3/3]

micro_os_plus::micro_test_plus::detail::timestamps::timestamps ( timestamps && )

delete

References timestamps().

~timestamps()

micro_os_plus::micro_test_plus::detail::timestamps::~timestamps ( )

default

References compute_elapsed_time(), has_end(), and has_timestamps().

Member Function Documentation

compute_elapsed_time()

void micro_os_plus::micro_test_plus::detail::timestamps::compute_elapsed_time	(	uint32_t &	milliseconds,
		uint32_t &	microseconds ) const

Parameters

[out]	milliseconds	The elapsed time in whole milliseconds.
[out]	microseconds	The sub-millisecond remainder in microseconds.

Subtracts the begin timestamp from the end timestamp in nanoseconds. If the nanosecond difference is negative, one second is borrowed from the seconds delta to normalise the result. The total elapsed duration in microseconds is then split into whole milliseconds (written to milliseconds) and the remainder microseconds (written to microseconds). Requires has_timestamps() to be true; behaviour is undefined otherwise.

Definition at line 192 of file timings.cpp.

  {
    assert (has_timestamps ());
 
    // Precondition: has_timestamps() must be true before calling this method.
    // Invoking it with disengaged optionals is undefined behaviour.
    long long delta_ns
        = end_time_->value ().tv_nsec - begin_time_->value ().tv_nsec;
    long long delta_s
        = end_time_->value ().tv_sec - begin_time_->value ().tv_sec;
    if (delta_ns < 0)
      {
        delta_ns += 1000000000LL;
        --delta_s;
      }
 
    // Split into milliseconds and microseconds.
    const long long total_us = delta_s * 1000000LL + delta_ns / 1000LL;
    milliseconds = static_cast<uint32_t> (total_us / 1000LL);
    microseconds = static_cast<uint32_t> (total_us % 1000LL);
  }

References begin_time_, end_time_, and has_timestamps().

Referenced by ~timestamps(), micro_os_plus::micro_test_plus::reporter_human::end_session(), micro_os_plus::micro_test_plus::reporter_tap::end_session(), micro_os_plus::micro_test_plus::reporter_human::end_suite(), and micro_os_plus::micro_test_plus::reporter_tap::end_suite().

has_begin()

bool micro_os_plus::micro_test_plus::detail::timestamps::has_begin ( ) const

inlinenoexcept

Parameters

None.

Return values

true	timestamp_begin() has been called.
false	timestamp_begin() has not been called.

Returns true when begin_time_ holds a value, i.e. when timestamp_begin() has previously been called.

Definition at line 89 of file timings-inlines.h.

  {
    return begin_time_.has_value ();
  }

References begin_time_.

has_end()

bool micro_os_plus::micro_test_plus::detail::timestamps::has_end ( ) const

inlinenoexcept

Parameters

None.

Return values

true	timestamp_end() has been called.
false	timestamp_end() has not been called.

Returns true when end_time_ holds a value, i.e. when timestamp_end() has previously been called.

Definition at line 100 of file timings-inlines.h.

  {
    return end_time_.has_value ();
  }

References end_time_.

Referenced by ~timestamps().

has_timestamps()

bool micro_os_plus::micro_test_plus::detail::timestamps::has_timestamps ( void ) const

noexcept

Parameters

None.

Return values

true	Both timestamps are present and elapsed time can be computed.
false	At least one timestamp is absent; elapsed time is not available.

Returns true only when both the begin and end optional timestamps are engaged and each contains a valid (non-zero) clock reading, as determined by timestamp::has_clock().

Definition at line 175 of file timings.cpp.

  {
    return begin_time_.has_value () && begin_time_->has_clock ()
           && end_time_.has_value () && end_time_->has_clock ();
  }

References begin_time_, and end_time_.

Referenced by ~timestamps(), compute_elapsed_time(), micro_os_plus::micro_test_plus::reporter_human::end_session(), micro_os_plus::micro_test_plus::reporter_tap::end_session(), micro_os_plus::micro_test_plus::reporter_human::end_suite(), and micro_os_plus::micro_test_plus::reporter_tap::end_suite().

operator=() [1/2]

timestamps & micro_os_plus::micro_test_plus::detail::timestamps::operator= ( const timestamps & )

delete

References timestamps().

operator=() [2/2]

timestamps & micro_os_plus::micro_test_plus::detail::timestamps::operator= ( timestamps && )

delete

References timestamps().

timestamp_begin() [1/2]

void micro_os_plus::micro_test_plus::detail::timestamps::timestamp_begin ( const timespec & ts )

noexcept

Parameters

ts	The timespec value to use as the begin timestamp.

Returns

Nothing.

If the begin timestamp has not yet been set, a timestamp is constructed in-place from the supplied timespec value. Subsequent calls are silently ignored, ensuring idempotent behaviour.

Definition at line 126 of file timings.cpp.

  {
    // Ensure it is timestamped only once.
    if (!begin_time_.has_value ())
      {
        begin_time_.emplace (ts);
      }
  }

References begin_time_.

timestamp_begin() [2/2]

void micro_os_plus::micro_test_plus::detail::timestamps::timestamp_begin ( void )

noexcept

Parameters

None.

Returns

Nothing.

If the begin timestamp has not yet been set, a timestamp is constructed in-place using the default constructor, which captures the current monotonic time. Subsequent calls are silently ignored, ensuring idempotent behaviour.

Definition at line 110 of file timings.cpp.

  {
    // Ensure it is timestamped only once.
    if (!begin_time_.has_value ())
      {
        begin_time_.emplace ();
      }
  }

References begin_time_.

timestamp_end() [1/2]

void micro_os_plus::micro_test_plus::detail::timestamps::timestamp_end ( const timespec & ts )

noexcept

Parameters

ts	The timespec value to use as the end timestamp.

Returns

Nothing.

If the end timestamp has not yet been set, a timestamp is constructed in-place from the supplied timespec value. Subsequent calls are silently ignored, ensuring idempotent behaviour.

Definition at line 159 of file timings.cpp.

  {
    // Ensure it is timestamped only once.
    if (!end_time_.has_value ())
      {
        end_time_.emplace (ts);
      }
  }

References end_time_.

timestamp_end() [2/2]

void micro_os_plus::micro_test_plus::detail::timestamps::timestamp_end ( void )

noexcept

Parameters

None.

Returns

Nothing.

If the end timestamp has not yet been set, a timestamp is constructed in-place using the default constructor, which captures the current monotonic time. Subsequent calls are silently ignored, ensuring idempotent behaviour.

Definition at line 143 of file timings.cpp.

  {
    // Ensure it is timestamped only once.
    if (!end_time_.has_value ())
      {
        end_time_.emplace ();
      }
  }

References end_time_.

Member Data Documentation

begin_time_

std::optional<timestamp> micro_os_plus::micro_test_plus::detail::timestamps::begin_time_

protected

Definition at line 333 of file timings.h.

Referenced by compute_elapsed_time(), has_begin(), has_timestamps(), timestamp_begin(), and timestamp_begin().

end_time_

std::optional<timestamp> micro_os_plus::micro_test_plus::detail::timestamps::end_time_

protected

Definition at line 338 of file timings.h.

Referenced by compute_elapsed_time(), has_end(), has_timestamps(), timestamp_end(), and timestamp_end().

---

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

• timings.h
• timings-inlines.h
• timings.cpp