stopwatch Class

Measures the elapsed time of an operation. More...

Declaration

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

Included Headers

#include "micro-os-plus/micro-test-plus.h"

Friends Index

struct	stopwatch_test_access
	The unit tests helper, which sets known readings. More...

Public Constructors Index

	stopwatch (const stopwatch &)=delete
	Deleted copy constructor to prevent copying. More...
	stopwatch (stopwatch &&)=delete
	Deleted move constructor to prevent moving. More...
	stopwatch (void)=default
	Default constructor. More...

Public Destructor Index

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

Public Operators Index

stopwatch &	operator= (const stopwatch &)=delete
	Deleted copy assignment operator to prevent copying. More...
stopwatch &	operator= (stopwatch &&)=delete
	Deleted move assignment operator to prevent moving. More...

Public Member Functions Index

std::chrono::microseconds	elapsed (void) const noexcept
	Returns the time elapsed between start() and stop(). More...
bool	has_elapsed (void) const noexcept
	Checks whether the elapsed time is available. More...
void	start (void) noexcept
	Records the start time, from the system clock. More...
void	stop (void) noexcept
	Records the stop time, from the system clock. More...

Private Member Attributes Index

timespec	start_time_ {}
	The clock reading at the start of the measured interval. More...
timespec	stop_time_ {}
	The clock reading at the end of the measured interval. More...

Private Static Functions Index

static bool	is_recorded (const timespec &ts) noexcept
	Checks whether a clock reading was recorded. More...

Deprecated Functions Index

bool	has_begin (void) const noexcept
	Deprecated check of the start reading. More...
bool	has_end (void) const noexcept
	Deprecated check of the stop reading. More...
bool	has_timestamps (void) const noexcept
	Deprecated name of has_elapsed(). More...
void	compute_elapsed_time (uint32_t &milliseconds, uint32_t &microseconds) const noexcept
	Deprecated split of the elapsed time. More...
void	timestamp_begin (void) noexcept
	Deprecated recording of the start time, from the system clock. More...
void	timestamp_begin (const timespec &ts) noexcept
	Deprecated recording of a given start time. More...
void	timestamp_end (void) noexcept
	Deprecated recording of the stop time, from the system clock. More...
void	timestamp_end (const timespec &ts) noexcept
	Deprecated recording of a given stop time. More...

Description

Measures the elapsed time of an operation.

start() reads the system clock just before the measured operation and stop() just after it; when both readings are available, elapsed() returns the interval between them.

Each call reads the clock again: start() restarts the measurement, discarding both previous readings, and stop() replaces the previous stop reading, if any. A zero reading means that the clock was not read, either because the stopwatch was not started (or stopped), or because the platform has no clock; in both cases has_elapsed() returns false, so that the reporters can skip the timing output.

Typical usage in the framework:

1. Call start() just before the test suite or session body executes.
2. Call stop() immediately after it completes.
3. The reporters display elapsed(), when has_elapsed().

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

The class is final; the non-public members are private, and only the unit tests, through a friend, set known readings.

The public members of the v5.0.1 detail::timestamps class (timestamp_begin(), timestamp_end(), has_begin(), has_end(), has_timestamps(), and compute_elapsed_time()) are kept, deprecated, for the applications that used the deprecated timings() of the runner and of the suites, which return a reference to this class.

Definition at line 137 of file stopwatch.h.

Friends

stopwatch_test_access

friend struct stopwatch_test_access

The unit tests helper, which sets known readings.

It is declared here, and defined by the unit tests only, so that the tests can inject readings without deriving from the class.

Definition at line 408 of file stopwatch.h.

408 friend struct stopwatch_test_access;

References is_recorded and stopwatch_test_access.

Referenced by stopwatch_test_access.

Public Constructors

stopwatch()

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

delete

Deleted copy constructor to prevent copying.

The timing state belongs to a single suite or runner.

Definition at line 155 of file stopwatch.h.

Reference stopwatch.

stopwatch()

micro_os_plus::micro_test_plus::detail::stopwatch::stopwatch (stopwatch &&)

delete

Deleted move constructor to prevent moving.

The instance is a member of an object that is itself non-movable.

Definition at line 163 of file stopwatch.h.

Reference stopwatch.

stopwatch()

micro_os_plus::micro_test_plus::detail::stopwatch::stopwatch (void)

default

Default constructor.

Both readings are initially zero; they are set by start() and stop().

Definition at line 147 of file stopwatch.h.

Referenced by stopwatch, stopwatch, operator= and operator=.

Public Destructor

~stopwatch()

micro_os_plus::micro_test_plus::detail::stopwatch::~stopwatch ()

default

Defaulted destructor.

No resources are owned, so there is nothing to release.

Definition at line 191 of file stopwatch.h.

References compute_elapsed_time, elapsed, has_begin, has_elapsed, has_end, has_timestamps, start, stop, timestamp_begin and timestamp_end.

Public Operators

operator=()

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

delete

Deleted copy assignment operator to prevent copying.

The timing state belongs to a single suite or runner.

Definition at line 172 of file stopwatch.h.

Reference stopwatch.

operator=()

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

delete

Deleted move assignment operator to prevent moving.

The instance is a member of an object that is itself non-movable.

Definition at line 182 of file stopwatch.h.

Reference stopwatch.

Public Member Functions

elapsed()

std::chrono::microseconds micro_os_plus::micro_test_plus::detail::stopwatch::elapsed (void)

nodiscard noexcept

Returns the time elapsed between start() and stop().

The interval is truncated to whole microseconds. Without both readings (see has_elapsed()), the elapsed time is zero.

Parameters

None.

Returns

The elapsed time, in microseconds.

Converts the differences of the seconds and of the nanoseconds members to a single nanoseconds duration, so that a negative nanoseconds difference borrows from the seconds without explicit normalisation, and truncates the result to whole microseconds. If has_elapsed() is false, the result is zero.

Declaration at line 252 of file stopwatch.h, definition at line 116 of file stopwatch.cpp.

116 stopwatch::elapsed (void) const noexcept

117 {

118 if (!has_elapsed ())

119 {

120 return std::chrono::microseconds::zero ();

121 }

122

123 const std::chrono::nanoseconds delta = std::chrono::seconds{

124 stop_time_.tv_sec - start_time_.tv_sec

125 } + std::chrono::nanoseconds{ stop_time_.tv_nsec - start_time_.tv_nsec };

126

127 return std::chrono::duration_cast<std::chrono::microseconds> (delta);

128 }

References has_elapsed, start_time_ and stop_time_.

Referenced by ~stopwatch, compute_elapsed_time and micro_os_plus::micro_test_plus::detail::reporter::format_elapsed_time.

has_elapsed()

bool micro_os_plus::micro_test_plus::detail::stopwatch::has_elapsed (void)

inline nodiscard noexcept

Checks whether the elapsed time is available.

The elapsed time is available after both start() and stop() were called, on a platform with a clock.

Parameters

None.

Return Values

true	Both readings are available; elapsed() returns the measured interval.
false	At least one reading is absent; elapsed() returns zero.

Returns true only when both the start and the stop readings were recorded, as determined by is_recorded().

Declaration at line 238 of file stopwatch.h, definition at line 64 of file stopwatch-inlines.h.

64 stopwatch::has_elapsed (void) const noexcept

65 {

66 return is_recorded (start_time_) && is_recorded (stop_time_);

67 }

References is_recorded, start_time_ and stop_time_.

Referenced by ~stopwatch, elapsed and has_timestamps.

start()

void micro_os_plus::micro_test_plus::detail::stopwatch::start (void)

noexcept

Records the start time, from the system clock.

Each call restarts the measurement: the stop reading is cleared, so has_elapsed() is false until the next stop().

Parameters

None.

Returns

Nothing.

Clears both readings, then reads the system clock into start_time_. The readings are cleared first because read_clock() leaves its argument unchanged on the platforms without a clock, where a previous reading would otherwise survive.

Declaration at line 206 of file stopwatch.h, definition at line 87 of file stopwatch.cpp.

87 stopwatch::start (void) noexcept

88 {

89 start_time_ = {};

90 stop_time_ = {};

91 read_clock (start_time_);

92 }

References micro_os_plus::micro_test_plus::detail::read_clock, start_time_ and stop_time_.

Referenced by ~stopwatch, micro_os_plus::micro_test_plus::runner::add_top_suite, micro_os_plus::micro_test_plus::runner::initialise and micro_os_plus::micro_test_plus::suite::run.

stop()

void micro_os_plus::micro_test_plus::detail::stopwatch::stop (void)

noexcept

Records the stop time, from the system clock.

Each call replaces the previous stop reading, if any, so the elapsed time is measured from the start to the last stop().

Parameters

None.

Returns

Nothing.

Clears the stop reading, then reads the system clock into stop_time_, for the same reason as in start(). The start reading is not changed.

Declaration at line 221 of file stopwatch.h, definition at line 101 of file stopwatch.cpp.

101 stopwatch::stop (void) noexcept

102 {

103 stop_time_ = {};

104 read_clock (stop_time_);

105 }

References micro_os_plus::micro_test_plus::detail::read_clock and stop_time_.

Referenced by ~stopwatch, micro_os_plus::micro_test_plus::suite::run and micro_os_plus::micro_test_plus::runner::run_suites.

Private Member Attributes

start_time_

timespec micro_os_plus::micro_test_plus::detail::stopwatch::start_time_ {}

The clock reading at the start of the measured interval.

Zero until start() is called; set again by each start().

Definition at line 430 of file stopwatch.h.

430 timespec start_time_{};

Referenced by elapsed, has_begin, has_elapsed, start, timestamp_begin and timestamp_begin.

stop_time_

timespec micro_os_plus::micro_test_plus::detail::stopwatch::stop_time_ {}

The clock reading at the end of the measured interval.

Zero until stop() is called; set again by each stop(), and cleared by start().

Definition at line 439 of file stopwatch.h.

439 timespec stop_time_{};

Referenced by elapsed, has_elapsed, has_end, start, stop, timestamp_end and timestamp_end.

Private Static Functions

is_recorded()

bool micro_os_plus::micro_test_plus::detail::stopwatch::is_recorded (const timespec & ts)

inline nodiscard noexcept static

Checks whether a clock reading was recorded.

A zero timespec means that the clock was not read, or that the platform has no clock.

Parameters

ts	The clock reading to check.

Return Values

true	At least one of the members is not zero.
false	Both members are zero.

Returns true if at least one of the tv_sec or tv_nsec members of ts is non-zero, indicating that a clock reading was captured.

Declaration at line 422 of file stopwatch.h, definition at line 75 of file stopwatch-inlines.h.

75 stopwatch::is_recorded (const timespec& ts) noexcept

76 {

77 return ts.tv_sec != 0 || ts.tv_nsec != 0;

78 }

Referenced by has_begin, has_elapsed, has_end, stopwatch_test_access, timestamp_begin, timestamp_begin, timestamp_end and timestamp_end.

Deprecated Functions

compute_elapsed_time()

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

inline noexcept

Deprecated split of the elapsed time.

Kept from the v5.0.1 detail::timestamps class. Splits the value returned by elapsed() into whole milliseconds and the remaining microseconds. Without both readings, both are zero; in v5.0.1, the call was not allowed (it asserted).

Parameters

[out] milliseconds	The whole milliseconds of the elapsed time.
[out] microseconds	The remaining microseconds, from 0 to 999.

Returns

Nothing.

Deprecated

use elapsed() (since 6.0.0)

Divides the microseconds count returned by elapsed() by 1000; the conversions to uint32_t truncate the intervals longer than about 49 days, as in v5.0.1.

Declaration at line 324 of file stopwatch.h, definition at line 126 of file stopwatch-inlines.h.

126 stopwatch::compute_elapsed_time (uint32_t& milliseconds,

127 uint32_t& microseconds) const noexcept

128 {

129 const auto count = elapsed ().count ();

130 milliseconds = static_cast<uint32_t> (count / 1000);

131 microseconds = static_cast<uint32_t> (count % 1000);

132 }

Reference elapsed.

Referenced by ~stopwatch.

has_begin()

bool micro_os_plus::micro_test_plus::detail::stopwatch::has_begin (void)

inline nodiscard noexcept

Deprecated check of the start reading.

Kept from the v5.0.1 detail::timestamps class. The start reading is available after start(), on a platform with a clock; in v5.0.1, it was also reported without a clock.

Parameters

None.

Return Values

true	The start reading is available.
false	The start reading is absent.

Deprecated

use has_elapsed() (since 6.0.0)

Returns true if the start reading was recorded, as determined by is_recorded().

Declaration at line 274 of file stopwatch.h, definition at line 90 of file stopwatch-inlines.h.

90 stopwatch::has_begin (void) const noexcept

91 {

92 return is_recorded (start_time_);

93 }

References is_recorded and start_time_.

Referenced by ~stopwatch.

has_end()

bool micro_os_plus::micro_test_plus::detail::stopwatch::has_end (void)

inline nodiscard noexcept

Deprecated check of the stop reading.

Kept from the v5.0.1 detail::timestamps class. The stop reading is available after stop(), on a platform with a clock, until the next start(); in v5.0.1, it was also reported without a clock.

Parameters

None.

Return Values

true	The stop reading is available.
false	The stop reading is absent.

Deprecated

use has_elapsed() (since 6.0.0)

Returns true if the stop reading was recorded, as determined by is_recorded().

Declaration at line 291 of file stopwatch.h, definition at line 102 of file stopwatch-inlines.h.

102 stopwatch::has_end (void) const noexcept

103 {

104 return is_recorded (stop_time_);

105 }

References is_recorded and stop_time_.

Referenced by ~stopwatch.

has_timestamps()

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

inline nodiscard noexcept

Deprecated name of has_elapsed().

Kept from the v5.0.1 detail::timestamps class; calls has_elapsed().

Parameters

None.

Returns

The value returned by has_elapsed().

Deprecated

use has_elapsed() (since 6.0.0)

Forwards to has_elapsed().

Declaration at line 305 of file stopwatch.h, definition at line 113 of file stopwatch-inlines.h.

113 stopwatch::has_timestamps (void) const noexcept

114 {

115 return has_elapsed ();

116 }

Reference has_elapsed.

Referenced by ~stopwatch.

timestamp_begin()

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

noexcept

Deprecated recording of the start time, from the system clock.

Kept from the v5.0.1 detail::timestamps class. Unlike start(), it reads the clock only if the start reading is absent, and it does not clear the stop reading. In v5.0.1, a reading taken without a clock was also kept; here, the next call reads the clock again.

Parameters

None.

Returns

Nothing.

Deprecated

use start() (since 6.0.0)

Reads the system clock into start_time_ only if is_recorded() reports no start reading; since the reading is zero in that case, it need not be cleared first, as in start().

Declaration at line 344 of file stopwatch.h, definition at line 139 of file stopwatch.cpp.

139 stopwatch::timestamp_begin (void) noexcept

140 {

141 if (!is_recorded (start_time_))

142 {

143 read_clock (start_time_);

144 }

145 }

References is_recorded, micro_os_plus::micro_test_plus::detail::read_clock and start_time_.

Referenced by ~stopwatch.

timestamp_begin()

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

inline noexcept

Deprecated recording of a given start time.

Kept from the v5.0.1 detail::timestamps class. Stores ts as the start reading, only if the start reading is absent; the stop reading is not changed. A zero ts leaves the reading absent; in v5.0.1, it was stored, and reported by has_begin().

Parameters

ts	The start time.

Returns

Nothing.

Deprecated

use start() (since 6.0.0)

Stores ts only if is_recorded() reports no start reading.

Declaration at line 360 of file stopwatch.h, definition at line 140 of file stopwatch-inlines.h.

140 stopwatch::timestamp_begin (const timespec& ts) noexcept

141 {

142 if (!is_recorded (start_time_))

143 {

144 start_time_ = ts;

145 }

146 }

References is_recorded and start_time_.

timestamp_end()

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

noexcept

Deprecated recording of the stop time, from the system clock.

Kept from the v5.0.1 detail::timestamps class. Unlike stop(), it reads the clock only if the stop reading is absent, so the elapsed time is measured to the first call, not to the last one.

Parameters

None.

Returns

Nothing.

Deprecated

use stop() (since 6.0.0)

Reads the system clock into stop_time_ only if is_recorded() reports no stop reading, for the same reason as in timestamp_begin().

Declaration at line 377 of file stopwatch.h, definition at line 155 of file stopwatch.cpp.

155 stopwatch::timestamp_end (void) noexcept

156 {

157 if (!is_recorded (stop_time_))

158 {

159 read_clock (stop_time_);

160 }

161 }

References is_recorded, micro_os_plus::micro_test_plus::detail::read_clock and stop_time_.

Referenced by ~stopwatch.

timestamp_end()

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

inline noexcept

Deprecated recording of a given stop time.

Kept from the v5.0.1 detail::timestamps class. Stores ts as the stop reading, only if the stop reading is absent. A zero ts leaves the reading absent; in v5.0.1, it was stored, and reported by has_end().

Parameters

ts	The stop time.

Returns

Nothing.

Deprecated

use stop() (since 6.0.0)

Stores ts only if is_recorded() reports no stop reading.

Declaration at line 393 of file stopwatch.h, definition at line 154 of file stopwatch-inlines.h.

154 stopwatch::timestamp_end (const timespec& ts) noexcept

155 {

156 if (!is_recorded (stop_time_))

157 {

158 stop_time_ = ts;

159 }

160 }

References is_recorded and stop_time_.

---

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

• stopwatch-inlines.h
• stopwatch.h
• stopwatch.cpp

---

Generated via doxygen2docusaurus 2.2.8 by Doxygen 1.18.0.