stopwatch.h File

C++ header file with declarations for the µTest++ stopwatch. More...

Included Headers

#include <chrono> #include <cstdint> #include <ctime> #include "inlines/stopwatch-inlines.h"

Namespaces Index

namespace	micro_os_plus
	The primary namespace for the µOS++ framework. More...
namespace	micro_test_plus
	Primary namespace for the µTest++ testing framework. More...
namespace	detail
	Internal implementation details for the µTest++ framework. More...

Classes Index

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

Functions Index

void	read_clock (timespec &ts) noexcept
	Reads the system clock. More...

Description

C++ header file with declarations for the µTest++ stopwatch.

This header provides the stopwatch class, used to measure the elapsed time of the test suites and of the test session within the µTest++ framework. The stopwatch is started before the measured operation, stopped after it, and then reports the elapsed time as a std::chrono::microseconds duration.

Timing support relies on clock_gettime(CLOCK_MONOTONIC, ...) on POSIX platforms and on timespec_get(..., TIME_UTC) on Windows. If no clock is available (e.g. on bare-metal targets without an RTC), the readings remain zero, has_elapsed() returns false, and no timing information is reported.

All definitions reside within the micro_os_plus::micro_test_plus::detail namespace.

This file is included by micro-os-plus/micro-test-plus.h, which is the header that the applications include.

Functions

read_clock()

void micro_os_plus::micro_test_plus::detail::read_clock (timespec & ts)

noexcept

Reads the system clock.

Isolates the platform-specific access to the system clock, used by stopwatch and by the deprecated timestamp class. The clock is monotonic on POSIX; without a clock, ts is left unchanged, so the callers clear it first when a zero value must mean that the clock was not read.

Parameters

[out] ts

The timespec where the reading is stored.

Returns

Nothing.

On Windows, the current time is captured via timespec_get() with TIME_UTC. On POSIX platforms with CLOCK_MONOTONIC defined, clock_gettime(CLOCK_MONOTONIC) is used to obtain a monotonic reading. On platforms where neither macro is defined, ts is left unchanged.

Definition at line 66 of file stopwatch.cpp.

66 read_clock (timespec& ts) noexcept

67 {

68#if defined(_WIN32)

69 timespec_get (&ts, TIME_UTC);

70#elif defined(CLOCK_MONOTONIC)

71 clock_gettime (CLOCK_MONOTONIC, &ts);

72#else

73 (void)ts;

74#endif // defined(_WIN32) || defined(CLOCK_MONOTONIC)

75 }

Reference micro_os_plus::micro_test_plus::detail::read_clock.

Referenced by micro_os_plus::micro_test_plus::detail::timestamp::timestamp, micro_os_plus::micro_test_plus::detail::read_clock, micro_os_plus::micro_test_plus::detail::stopwatch::start, micro_os_plus::micro_test_plus::detail::stopwatch::stop, micro_os_plus::micro_test_plus::detail::stopwatch::timestamp_begin and micro_os_plus::micro_test_plus::detail::stopwatch::timestamp_end.

File Listing

The file content with the documentation metadata removed is:

1// ----------------------------------------------------------------------------

2/*

3 * This file is part of the µOS++ project (https://micro-os-plus.github.io/).

4 * Copyright (c) 2021-2026 Liviu Ionescu. All rights reserved.

5 *

6 * Permission to use, copy, modify, and/or distribute this software for any

7 * purpose is hereby granted, under the terms of the MIT license.

8 *

9 * If a copy of the license was not distributed with this file, it can be

10 * obtained from https://opensource.org/licenses/mit.

11 */

12

13// ----------------------------------------------------------------------------

14

38

39#ifndef MICRO_OS_PLUS_MICRO_TEST_PLUS_STOPWATCH_H_

40#define MICRO_OS_PLUS_MICRO_TEST_PLUS_STOPWATCH_H_

41

42// ----------------------------------------------------------------------------

43

44#if defined(__cplusplus)

45

46// ----------------------------------------------------------------------------

47

48#if __has_include("micro-os-plus/project-config.h")

49#include "micro-os-plus/project-config.h"

50#endif // __has_include("micro-os-plus/project-config.h")

51

52#if __has_include("micro-os-plus/micro-test-plus-defines.h")

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

54#endif // __has_include("micro-os-plus/micro-test-plus-defines.h")

55

56#include <chrono>

57#include <cstdint>

58#include <ctime>

59

60// ----------------------------------------------------------------------------

61

62#if defined(__GNUC__)

63#pragma GCC diagnostic push

64

65#if defined(__clang__)

66#pragma clang diagnostic ignored "-Wc++98-compat"

67#pragma clang diagnostic ignored "-Wpre-c++17-compat"

68#endif // defined(__clang__)

69#endif // defined(__GNUC__)

70

71// ============================================================================

72

73namespace micro_os_plus::micro_test_plus

74{

75 // --------------------------------------------------------------------------

76

77 namespace detail

78 {

79 // ========================================================================

80

95 void

96 read_clock (timespec& ts) noexcept;

97

98 // ========================================================================

99

137 class stopwatch final

138 {

139 public:

147 stopwatch (void) = default;

148

155 stopwatch (const stopwatch&) = delete;

156

163 stopwatch (stopwatch&&) = delete;

164

171 stopwatch&

172 operator=(const stopwatch&)

173 = delete;

174

181 stopwatch&

182 operator=(stopwatch&&)

183 = delete;

184

191 ~stopwatch () = default;

192

205 void

206 start (void) noexcept;

207

220 void

221 stop (void) noexcept;

222

237 [[nodiscard]] bool

238 has_elapsed (void) const noexcept;

239

251 [[nodiscard]] std::chrono::microseconds

252 elapsed (void) const noexcept;

253

254#if defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)

259

273 [[deprecated ("use has_elapsed() (since 6.0.0)"), nodiscard]] bool

274 has_begin (void) const noexcept;

275

290 [[deprecated ("use has_elapsed() (since 6.0.0)"), nodiscard]] bool

291 has_end (void) const noexcept;

292

304 [[deprecated ("use has_elapsed() (since 6.0.0)"), nodiscard]] bool

305 has_timestamps (void) const noexcept;

306

323 [[deprecated ("use elapsed() (since 6.0.0)")]] void

324 compute_elapsed_time (uint32_t& milliseconds,

325 uint32_t& microseconds) const noexcept;

326

343 [[deprecated ("use start() (since 6.0.0)")]] void

344 timestamp_begin (void) noexcept;

345

359 [[deprecated ("use start() (since 6.0.0)")]] void

360 timestamp_begin (const timespec& ts) noexcept;

361

376 [[deprecated ("use stop() (since 6.0.0)")]] void

377 timestamp_end (void) noexcept;

378

392 [[deprecated ("use stop() (since 6.0.0)")]] void

393 timestamp_end (const timespec& ts) noexcept;

394

398#endif // defined(MICRO_OS_PLUS_MICRO_TEST_PLUS_DEPRECATED_ENABLED)

399

400 private:

408 friend struct stopwatch_test_access;

409

421 [[nodiscard]] static bool

422 is_recorded (const timespec& ts) noexcept;

423

430 timespec start_time_{};

431

439 timespec stop_time_{};

440 };

441

442 // ------------------------------------------------------------------------

443 } // namespace detail

444 // ==========================================================================

445} // namespace micro_os_plus::micro_test_plus

446

447#if defined(__GNUC__)

448#pragma GCC diagnostic pop

449#endif // defined(__GNUC__)

450

451// ----------------------------------------------------------------------------

452

453#endif // defined(__cplusplus)

454

455// ============================================================================

456// Templates, inlines & constexpr implementations.

457

458#include "inlines/stopwatch-inlines.h"

459

460// ----------------------------------------------------------------------------

461

462#endif // MICRO_OS_PLUS_MICRO_TEST_PLUS_STOPWATCH_H_

463

464// ----------------------------------------------------------------------------

---

Generated via doxygen2docusaurus 2.2.8 by Doxygen 1.18.0.