micro_os_plus::micro_test_plus::detail::stopwatch Class Reference

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

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

Public Member Functions
	stopwatch (const stopwatch &)=delete
	Deleted copy constructor to prevent copying.
	stopwatch (stopwatch &&)=delete
	Deleted move constructor to prevent moving.
	stopwatch (void)=default
	Default constructor.
	~stopwatch ()=default
	Defaulted destructor.
std::chrono::microseconds	elapsed (void) const noexcept
	Returns the time elapsed between start() and stop().
bool	has_elapsed (void) const noexcept
	Checks whether the elapsed time is available.
stopwatch &	operator= (const stopwatch &)=delete
	Deleted copy assignment operator to prevent copying.
stopwatch &	operator= (stopwatch &&)=delete
	Deleted move assignment operator to prevent moving.
void	start (void) noexcept
	Records the start time, from the system clock.
void	stop (void) noexcept
	Records the stop time, from the system clock.
Deprecated Functions
bool	has_begin (void) const noexcept
	Deprecated check of the start reading.
bool	has_end (void) const noexcept
	Deprecated check of the stop reading.
bool	has_timestamps (void) const noexcept
	Deprecated name of has_elapsed().
void	compute_elapsed_time (uint32_t &milliseconds, uint32_t &microseconds) const noexcept
	Deprecated split of the elapsed time.
void	timestamp_begin (void) noexcept
	Deprecated recording of the start time, from the system clock.
void	timestamp_begin (const timespec &ts) noexcept
	Deprecated recording of a given start time.
void	timestamp_end (void) noexcept
	Deprecated recording of the stop time, from the system clock.
void	timestamp_end (const timespec &ts) noexcept
	Deprecated recording of a given stop time.

Static Private Member Functions
static bool	is_recorded (const timespec &ts) noexcept
	Checks whether a clock reading was recorded.

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

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

Detailed Description

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.

Constructor & Destructor Documentation

stopwatch() [1/3]

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

default

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

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

stopwatch() [2/3]

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

delete

The timing state belongs to a single suite or runner.

References stopwatch().

stopwatch() [3/3]

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

delete

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

References stopwatch().

~stopwatch()

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

default

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

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

Member Function Documentation

compute_elapsed_time()

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

inlinenoexcept

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.

Definition at line 126 of file stopwatch-inlines.h.

  {
    const auto count = elapsed ().count ();
    milliseconds = static_cast<uint32_t> (count / 1000);
    microseconds = static_cast<uint32_t> (count % 1000);
  }

References elapsed().

Referenced by ~stopwatch().

elapsed()

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

nodiscardnoexcept

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.

Definition at line 116 of file stopwatch.cpp.

  {
    if (!has_elapsed ())
      {
        return std::chrono::microseconds::zero ();
      }
 
    const std::chrono::nanoseconds delta = std::chrono::seconds{
      stop_time_.tv_sec - start_time_.tv_sec
    } + std::chrono::nanoseconds{ stop_time_.tv_nsec - start_time_.tv_nsec };
 
    return std::chrono::duration_cast<std::chrono::microseconds> (delta);
  }

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

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

inlinenodiscardnoexcept

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

Definition at line 90 of file stopwatch-inlines.h.

  {
    return is_recorded (start_time_);
  }

References is_recorded(), and start_time_.

Referenced by ~stopwatch().

has_elapsed()

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

inlinenodiscardnoexcept

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

Definition at line 64 of file stopwatch-inlines.h.

  {
    return is_recorded (start_time_) && is_recorded (stop_time_);
  }

References is_recorded(), start_time_, and stop_time_.

Referenced by ~stopwatch(), elapsed(), and has_timestamps().

has_end()

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

inlinenodiscardnoexcept

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

Definition at line 102 of file stopwatch-inlines.h.

  {
    return is_recorded (stop_time_);
  }

References is_recorded(), and stop_time_.

Referenced by ~stopwatch().

has_timestamps()

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

inlinenodiscardnoexcept

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

Definition at line 113 of file stopwatch-inlines.h.

  {
    return has_elapsed ();
  }

References has_elapsed().

Referenced by ~stopwatch().

is_recorded()

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

inlinestaticnodiscardprivatenoexcept

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.

Definition at line 75 of file stopwatch-inlines.h.

  {
    return ts.tv_sec != 0 || ts.tv_nsec != 0;
  }

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

operator=() [1/2]

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

delete

The timing state belongs to a single suite or runner.

References stopwatch().

operator=() [2/2]

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

delete

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

References stopwatch().

start()

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

noexcept

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.

Definition at line 87 of file stopwatch.cpp.

  {
    start_time_ = {};
    stop_time_ = {};
    read_clock (start_time_);
  }

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

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.

Definition at line 101 of file stopwatch.cpp.

  {
    stop_time_ = {};
    read_clock (stop_time_);
  }

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

timestamp_begin() [1/2]

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

inlinenoexcept

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.

Definition at line 140 of file stopwatch-inlines.h.

  {
    if (!is_recorded (start_time_))
      {
        start_time_ = ts;
      }
  }

References is_recorded(), and start_time_.

timestamp_begin() [2/2]

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

noexcept

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

Definition at line 139 of file stopwatch.cpp.

  {
    if (!is_recorded (start_time_))
      {
        read_clock (start_time_);
      }
  }

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

Referenced by ~stopwatch().

timestamp_end() [1/2]

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

inlinenoexcept

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.

Definition at line 154 of file stopwatch-inlines.h.

  {
    if (!is_recorded (stop_time_))
      {
        stop_time_ = ts;
      }
  }

References is_recorded(), and stop_time_.

timestamp_end() [2/2]

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

noexcept

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

Definition at line 155 of file stopwatch.cpp.

  {
    if (!is_recorded (stop_time_))
      {
        read_clock (stop_time_);
      }
  }

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

Referenced by ~stopwatch().

Friends And Related Symbol Documentation

stopwatch_test_access

friend struct stopwatch_test_access

friend

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.

References is_recorded(), and stopwatch_test_access.

Referenced by stopwatch_test_access.

Member Data Documentation

start_time_

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

private

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

Definition at line 430 of file stopwatch.h.

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_ {}

private

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

Definition at line 439 of file stopwatch.h.

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

---

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

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