@micro-os-plus/micro-test-plus 3.3.0 → 4.0.0

package/include/micro-os-plus/micro-test-plus/timings.h

@@ -0,0 +1,366 @@
+
+// ----------------------------------------------------------------------------
+/*
+ * This file is part of the µOS++ project (https://micro-os-plus.github.io/).
+ * Copyright (c) 2021-2026 Liviu Ionescu. All rights reserved.
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose is hereby granted, under the terms of the MIT license.
+ *
+ * If a copy of the license was not distributed with this file, it can be
+ * obtained from https://opensource.org/licenses/mit.
+ */
+
+// ----------------------------------------------------------------------------
+
+/**
+ * @file
+ * @brief C++ header file with declarations for the µTest++ timing utilities.
+ *
+ * @details
+ * This header provides two lightweight classes used to measure the elapsed
+ * time of test suites and test sessions within the µTest++ framework:
+ *
+ * - `timestamp` wraps a single `timespec` value and records one point in
+ *   time. It is default-constructible and trivially copyable.
+ * - `timestamps` pairs a begin and an end `timestamp` (both stored as
+ *   `std::optional<timestamp>`) and exposes methods for recording the
+ *   start and finish of an operation, querying whether both timestamps are
+ *   available, and computing the elapsed time in milliseconds and
+ *   microseconds.
+ *
+ * Timing support relies on `clock_gettime(CLOCK_MONOTONIC_RAW, ...)` when
+ * available; if the clock is not present (e.g. on bare-metal targets without
+ * an RTC) the timestamps are simply omitted and no timing information is
+ * reported.
+ *
+ * All definitions reside within the `micro_os_plus::micro_test_plus`
+ * namespace, ensuring clear separation from user code and minimising the
+ * risk of naming conflicts.
+ *
+ * This file is intended solely for internal use within the framework and
+ * should not be included directly by user code.
+ */
+
+#ifndef MICRO_TEST_PLUS_TIMINGS_H_
+#define MICRO_TEST_PLUS_TIMINGS_H_
+
+// ----------------------------------------------------------------------------
+
+#ifdef __cplusplus
+
+// ----------------------------------------------------------------------------
+
+#include <cstdint>
+#include <optional>
+#include <ctime>
+
+// ----------------------------------------------------------------------------
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wc++98-compat"
+#pragma clang diagnostic ignored "-Wpre-c++17-compat"
+#endif
+#endif
+
+// ===========================================================================
+
+namespace micro_os_plus::micro_test_plus
+{
+
+  // ==========================================================================
+
+  /**
+   * @brief A single point-in-time measurement, wrapping a `timespec` value.
+   *
+   * @details
+   * `timestamp` stores one `timespec` sample obtained from the system clock.
+   * It is default-constructible (zero-initialises the `timespec`),
+   * copy-constructible, and move-constructible, so that it can be used
+   * efficiently in `std::optional<timestamp>` containers.
+   *
+   * The `has_clock()` predicate allows callers to determine whether a
+   * real-time clock is available on the target platform before relying on
+   * the stored value.
+   *
+   * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+   */
+  class timestamp
+  {
+  public:
+    /**
+     * @brief Default constructor. Zero-initialises the internal `timespec`.
+     */
+    timestamp () noexcept;
+
+    /**
+     * @brief Constructs a timestamp from an existing `timespec` value.
+     *
+     * @param ts The `timespec` value to store.
+     */
+    timestamp (const timespec& ts) noexcept : value_{ ts }
+    {
+    }
+
+    // `timespec` is trivially copyable, so copy and move are safe to default.
+    // Defaulting these operations allows `timestamp` to be used in contexts
+    // that require copyability or movability (e.g. containers, algorithms).
+    /**
+     * @brief Defaulted copy constructor.
+     */
+    timestamp (const timestamp&) = default;
+
+    /**
+     * @brief Defaulted move constructor.
+     */
+    timestamp (timestamp&&) = default;
+
+    /**
+     * @brief Defaulted copy assignment operator.
+     */
+    timestamp&
+    operator= (const timestamp&) = default;
+
+    /**
+     * @brief Defaulted move assignment operator.
+     */
+    timestamp&
+    operator= (timestamp&&) = default;
+
+    /**
+     * @brief Defaulted destructor.
+     */
+    ~timestamp () = default;
+
+    /**
+     * @brief Returns true if a monotonic clock is available on this target.
+     *
+     * @par Parameters
+     *   None.
+     * @retval true  A real-time clock is available and timestamps are valid.
+     * @retval false No clock is available; timing data should be ignored.
+     */
+    bool
+    has_clock (void) const noexcept;
+
+    /**
+     * @brief Returns a mutable reference to the underlying `timespec` value.
+     *
+     * @par Parameters
+     *   None.
+     * @return A reference to the stored `timespec`.
+     */
+    [[nodiscard]] timespec&
+    value () noexcept
+    {
+      return value_;
+    }
+
+    /**
+     * @brief Returns a const reference to the underlying `timespec` value.
+     *
+     * @par Parameters
+     *   None.
+     * @return A const reference to the stored `timespec`.
+     */
+    [[nodiscard]] const timespec&
+    value () const noexcept
+    {
+      return value_;
+    }
+
+  protected:
+    /**
+     * @brief The underlying `timespec` value.
+     */
+    timespec value_{};
+  };
+
+  // ==========================================================================
+
+  /**
+   * @brief A begin/end timestamp pair used to measure elapsed time.
+   *
+   * @details
+   * `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.
+   *
+   * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+   */
+  class timestamps
+  {
+  public:
+    /**
+     * @brief Default constructor. Both timestamps are uninitialised.
+     */
+    timestamps () = default;
+
+    /**
+     * @brief Deleted copy constructor to prevent copying.
+     */
+    timestamps (const timestamps&) = delete;
+
+    /**
+     * @brief Deleted move constructor to prevent moving.
+     */
+    timestamps (timestamps&&) = delete;
+
+    /**
+     * @brief Deleted copy assignment operator to prevent copying.
+     */
+    timestamps&
+    operator= (const timestamps&) = delete;
+
+    /**
+     * @brief Deleted move assignment operator to prevent moving.
+     */
+    timestamps&
+    operator= (timestamps&&) = delete;
+
+    /**
+     * @brief Defaulted destructor.
+     */
+    ~timestamps () = default;
+
+    /**
+     * @brief Records the begin timestamp using the current system clock.
+     *
+     * @par Parameters
+     *   None.
+     * @par Returns
+     *   Nothing.
+     */
+    void
+    timestamp_begin (void) noexcept;
+
+    /**
+     * @brief Records the begin timestamp from a caller-supplied value.
+     *
+     * @param ts The `timespec` value to use as the begin timestamp.
+     * @par Returns
+     *   Nothing.
+     */
+    void
+    timestamp_begin (const timespec& ts) noexcept;
+
+    /**
+     * @brief Records the end timestamp using the current system clock.
+     *
+     * @par Parameters
+     *   None.
+     * @par Returns
+     *   Nothing.
+     */
+    void
+    timestamp_end (void) noexcept;
+
+    /**
+     * @brief Records the end timestamp from a caller-supplied value.
+     *
+     * @param ts The `timespec` value to use as the end timestamp.
+     * @par Returns
+     *   Nothing.
+     */
+    void
+    timestamp_end (const timespec& ts) noexcept;
+
+    /**
+     * @brief Returns true if the begin timestamp has been recorded.
+     *
+     * @par Parameters
+     *   None.
+     * @retval true  `timestamp_begin()` has been called.
+     * @retval false `timestamp_begin()` has not been called.
+     */
+    bool
+    has_begin () const noexcept
+    {
+      return begin_time_.has_value ();
+    }
+
+    /**
+     * @brief Returns true if the end timestamp has been recorded.
+     *
+     * @par Parameters
+     *   None.
+     * @retval true  `timestamp_end()` has been called.
+     * @retval false `timestamp_end()` has not been called.
+     */
+    bool
+    has_end () const noexcept
+    {
+      return end_time_.has_value ();
+    }
+
+    /**
+     * @brief Returns true if both begin and end timestamps are available.
+     *
+     * @par Parameters
+     *   None.
+     * @retval true  Both timestamps are present and elapsed time can be
+     *               computed.
+     * @retval false At least one timestamp is absent; elapsed time is not
+     *               available.
+     */
+    bool
+    has_timestamps (void) const noexcept;
+
+    /**
+     * @brief Computes the elapsed time between begin and end timestamps.
+     *
+     * @param[out] milliseconds The elapsed time in whole milliseconds.
+     * @param[out] microseconds The sub-millisecond remainder in microseconds.
+     *
+     * @details
+     * Both output parameters are only valid when `has_timestamps()` returns
+     * `true`. The caller is responsible for checking this precondition.
+     */
+    void
+    compute_elapsed_time (uint32_t& milliseconds,
+                          uint32_t& microseconds) const;
+
+  protected:
+    /**
+     * @brief The timestamp recorded at the beginning of the test suite.
+     */
+    std::optional<timestamp> begin_time_;
+
+    /**
+     * @brief The timestamp recorded at the end of the test suite.
+     */
+    std::optional<timestamp> end_time_;
+  };
+
+  // ==========================================================================
+
+} // namespace micro_os_plus::micro_test_plus
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
+
+// ----------------------------------------------------------------------------
+
+#endif // __cplusplus
+
+// ----------------------------------------------------------------------------
+
+#endif // MICRO_TEST_PLUS_TIMINGS_H_
+
+// ----------------------------------------------------------------------------