`timestamps` Class

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

Declaration

class micro_os_plus::micro_test_plus::detail::timestamps { ... }

Included Headers

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

Public Constructors Index

	timestamps ()=default
	Default constructor. Both timestamps are uninitialised. More...

	timestamps (const timestamps &)=delete
	Deleted copy constructor to prevent copying. More...

	timestamps (timestamps &&)=delete
	Deleted move constructor to prevent moving. More...

Public Destructor Index

	~timestamps ()=default
	Defaulted destructor. More...

Public Operators Index

timestamps &	operator= (const timestamps &)=delete
	Deleted copy assignment operator to prevent copying. More...

timestamps &	operator= (timestamps &&)=delete
	Deleted move assignment operator to prevent moving. More...

Public Member Functions Index

void	compute_elapsed_time (uint32_t &milliseconds, uint32_t &microseconds) const
	Computes the elapsed time between begin and end timestamps. More...

bool	has_begin () const noexcept
	Returns true if the begin timestamp has been recorded. More...

bool	has_end () const noexcept
	Returns true if the end timestamp has been recorded. More...

bool	has_timestamps (void) const noexcept
	Returns true if both begin and end timestamps are available. More...

void	timestamp_begin (const timespec &ts) noexcept
	Records the begin timestamp from a caller-supplied value. More...

void	timestamp_begin (void) noexcept
	Records the begin timestamp using the current system clock. More...

void	timestamp_end (const timespec &ts) noexcept
	Records the end timestamp from a caller-supplied value. More...

void	timestamp_end (void) noexcept
	Records the end timestamp using the current system clock. More...

Protected Member Attributes Index

std::optional< timestamp >	begin_time_
	The timestamp recorded at the beginning of the test suite. More...

std::optional< timestamp >	end_time_
	The timestamp recorded at the end of the test suite. More...

Description

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

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:

Call timestamp_begin() just before the test suite or session body executes.
Call timestamp_end() immediately after it completes.
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.

Public Constructors

timestamps()

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

default

Default constructor. Both timestamps are uninitialised.

Definition at line 210 of file timings.h.

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

timestamps()

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

delete

Deleted copy constructor to prevent copying.

Definition at line 215 of file timings.h.

Reference timestamps.

timestamps()

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

delete

Deleted move constructor to prevent moving.

Definition at line 220 of file timings.h.

Reference timestamps.

Public Destructor

~timestamps()

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

default

Defaulted destructor.

Definition at line 239 of file timings.h.

References compute_elapsed_time, has_end and has_timestamps.

Public Operators

operator=()

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

delete

Deleted copy assignment operator to prevent copying.

Definition at line 226 of file timings.h.

Reference timestamps.

operator=()

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

delete

Deleted move assignment operator to prevent moving.

Definition at line 233 of file timings.h.

Reference timestamps.

Public Member Functions

compute_elapsed_time()

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

Computes the elapsed time between begin and end timestamps.

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.

Declaration at line 326 of file timings.h, definition at line 184 of file timings.cpp.

184 timestamps::compute_elapsed_time (uint32_t& milliseconds,

185 uint32_t& microseconds) const

186 {

187 assert (has_timestamps ());

188

189 // Precondition: has_timestamps() must be true before calling this method.

190 // Invoking it with disengaged optionals is undefined behaviour.

191 long long delta_ns

192 = end_time_->value ().tv_nsec - begin_time_->value ().tv_nsec;

193 long long delta_s

194 = end_time_->value ().tv_sec - begin_time_->value ().tv_sec;

195 if (delta_ns < 0)

196 {

197 delta_ns += 1000000000LL;

198 --delta_s;

199 }

200

201 // Split into milliseconds and microseconds.

202 const long long total_us = delta_s * 1000000LL + delta_ns / 1000LL;

203 milliseconds = static_cast<uint32_t> (total_us / 1000LL);

204 microseconds = static_cast<uint32_t> (total_us % 1000LL);

205 }

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 ()

inline noexcept

Returns true if the begin timestamp has been recorded.

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.

Declaration at line 292 of file timings.h, definition at line 89 of file timings-inlines.h.

89 timestamps::has_begin () const noexcept

90 {

91 return begin_time_.has_value ();

92 }

Reference begin_time_.

has_end()

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

inline noexcept

Returns true if the end timestamp has been recorded.

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.

Declaration at line 303 of file timings.h, definition at line 100 of file timings-inlines.h.

100 timestamps::has_end () const noexcept

101 {

102 return end_time_.has_value ();

103 }

Reference end_time_.

Referenced by ~timestamps.

has_timestamps()

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

noexcept

Returns true if both begin and end timestamps are available.

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().

Declaration at line 316 of file timings.h, definition at line 167 of file timings.cpp.

167 timestamps::has_timestamps (void) const noexcept

168 {

169 return begin_time_.has_value () && begin_time_->has_clock ()

170 && end_time_.has_value () && end_time_->has_clock ();

171 }

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.

timestamp_begin()

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

noexcept

Records the begin timestamp from a caller-supplied value.

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.

Declaration at line 260 of file timings.h, definition at line 118 of file timings.cpp.

118 timestamps::timestamp_begin (const timespec& ts) noexcept

119 {

120 // Ensure it is timestamped only once.

121 if (!begin_time_.has_value ())

122 {

123 begin_time_.emplace (ts);

124 }

125 }

Reference begin_time_.

timestamp_begin()

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

noexcept

Records the begin timestamp using the current system clock.

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.

Declaration at line 250 of file timings.h, definition at line 102 of file timings.cpp.

102 timestamps::timestamp_begin (void) noexcept

103 {

104 // Ensure it is timestamped only once.

105 if (!begin_time_.has_value ())

106 {

107 begin_time_.emplace ();

108 }

109 }

Reference begin_time_.

Referenced by micro_os_plus::micro_test_plus::static_suite::run.

timestamp_end()

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

noexcept

Records the end timestamp from a caller-supplied value.

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.

Declaration at line 281 of file timings.h, definition at line 151 of file timings.cpp.

151 timestamps::timestamp_end (const timespec& ts) noexcept

152 {

153 // Ensure it is timestamped only once.

154 if (!end_time_.has_value ())

155 {

156 end_time_.emplace (ts);

157 }

158 }

Reference end_time_.

timestamp_end()

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

noexcept

Records the end timestamp using the current system clock.

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.

Declaration at line 271 of file timings.h, definition at line 135 of file timings.cpp.

135 timestamps::timestamp_end (void) noexcept

136 {

137 // Ensure it is timestamped only once.

138 if (!end_time_.has_value ())

139 {

140 end_time_.emplace ();

141 }

142 }

Reference end_time_.

Referenced by micro_os_plus::micro_test_plus::static_suite::run.

Protected Member Attributes

begin_time_

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

protected

The timestamp recorded at the beginning of the test suite.

Definition at line 333 of file timings.h.

333 std::optional<timestamp> begin_time_;

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

The timestamp recorded at the end of the test suite.

Definition at line 338 of file timings.h.

338 std::optional<timestamp> end_time_;

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:

Generated via doxygen2docusaurus 2.2.0 by Doxygen 1.17.0.

Declaration​

Included Headers​

Public Constructors Index​

Public Destructor Index​

Public Operators Index​

Public Member Functions Index​

Protected Member Attributes Index​

Description​

Public Constructors​

timestamps()​

timestamps()​

timestamps()​

Public Destructor​

~timestamps()​

Public Operators​

operator=()​

operator=()​

Public Member Functions​

compute_elapsed_time()​

has_begin()​

has_end()​

has_timestamps()​

timestamp_begin()​

timestamp_begin()​

timestamp_end()​

timestamp_end()​

Protected Member Attributes​

begin_time_​

end_time_​

Declaration

Included Headers

Public Constructors Index

Public Destructor Index

Public Operators Index

Public Member Functions Index

Protected Member Attributes Index

Description

Public Constructors

timestamps()

timestamps()

timestamps()

Public Destructor

~timestamps()

Public Operators

operator=()

operator=()

Public Member Functions

compute_elapsed_time()

has_begin()

has_end()

has_timestamps()

timestamp_begin()

timestamp_begin()

timestamp_end()

timestamp_end()

Protected Member Attributes

begin_time_

end_time_