system_clock.h

// Copyright 2020 The Pigweed Authors
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
// use this file except in compliance with the License. You may obtain a copy of
// the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
// License for the specific language governing permissions and limitations under
// the License.
#pragma once
 
#include <stddef.h>
#include <stdint.h>
 
#include "pw_preprocessor/util.h"
 
// The backend implements this header to provide the following SystemClock
// parameters, for more detail on the parameters see the SystemClock usage of
// them below:
//   PW_CHRONO_SYSTEM_CLOCK_PERIOD_SECONDS_NUMERATOR
//   PW_CHRONO_SYSTEM_CLOCK_PERIOD_SECONDS_DENOMINATOR
//   constexpr pw::chrono::Epoch pw::chrono::backend::kSystemClockEpoch;
//   constexpr bool pw::chrono::backend::kSystemClockFreeRunning;
//   constexpr bool pw::chrono::backend::kSystemClockNmiSafe;
#include "pw_chrono_backend/system_clock_config.h"
 
#ifdef __cplusplus
 
#include <chrono>
#include <ratio>
 
#include "pw_chrono/virtual_clock.h"
#include "pw_numeric/saturating_arithmetic.h"
 
namespace pw::chrono {
 
 
namespace backend {
 
int64_t GetSystemClockTickCount();
 
}  // namespace backend
 
struct SystemClock {
  using rep = int64_t;
  using period = std::ratio<PW_CHRONO_SYSTEM_CLOCK_PERIOD_SECONDS_NUMERATOR,
                            PW_CHRONO_SYSTEM_CLOCK_PERIOD_SECONDS_DENOMINATOR>;
  using duration = std::chrono::duration<rep, period>;
  using time_point = std::chrono::time_point<SystemClock>;
  static constexpr Epoch epoch = backend::kSystemClockEpoch;
 
  static constexpr bool is_monotonic = true;
  static constexpr bool is_steady = false;
 
  static constexpr bool is_free_running = backend::kSystemClockFreeRunning;
 
  static constexpr bool is_stopped_in_halting_debug_mode = true;
 
  static constexpr bool is_always_enabled = true;
 
  static constexpr bool is_nmi_safe = backend::kSystemClockNmiSafe;
 
  static time_point now() noexcept {
    return time_point(duration(backend::GetSystemClockTickCount()));
  }
 
  template <class Rep, class Period>
  static constexpr duration for_at_least(std::chrono::duration<Rep, Period> d) {
    return std::chrono::ceil<duration>(d);
  }
 
  static time_point TimePointAfterAtLeast(duration after_at_least) {
    rep ticks = backend::GetSystemClockTickCount() + 1;
    return time_point(duration(add_sat(ticks, after_at_least.count())));
  }
};
 
// NOTE: VirtualClock here is specialized on SystemClock in order to provide
// the `RealClock` function.
//
// SystemClock is defined in this file, so there's no risk of an ODR violation
// as other libraries are unable to spell VirtualClock<SystemClock> unless
// they have first included this file.
 
template <>
class VirtualClock<SystemClock> {
 public:
  static VirtualClock<SystemClock>& RealClock();
 
  virtual ~VirtualClock() = default;
 
  virtual SystemClock::time_point now() = 0;
};
 
using VirtualSystemClock = VirtualClock<SystemClock>;
 
}  // namespace pw::chrono
 
// The backend can opt to include an inlined implementation of the following:
//   int64_t GetSystemClockTickCount();
#if __has_include("pw_chrono_backend/system_clock_inline.h")
#include "pw_chrono_backend/system_clock_inline.h"
#endif  // __has_include("pw_chrono_backend/system_clock_inline.h")
 
#endif  // __cplusplus
 
// C API Users should not create pw_chrono_SystemClock_Duration's directly,
// instead it is strongly recommended to use macros which express the duration
// in time units, instead of non-portable ticks.
//
// The following macros round up just like std::chrono::ceil, this is the
// recommended rounding to maintain the "at least" contract of timeouts and
// deadlines (note the *_CEIL macros are the same only more explicit):
//   PW_SYSTEM_CLOCK_MS(milliseconds)
//   PW_SYSTEM_CLOCK_S(seconds)
//   PW_SYSTEM_CLOCK_MIN(minutes)
//   PW_SYSTEM_CLOCK_H(hours)
//   PW_SYSTEM_CLOCK_MS_CEIL(milliseconds)
//   PW_SYSTEM_CLOCK_S_CEIL(seconds)
//   PW_SYSTEM_CLOCK_MIN_CEIL(minutes)
//   PW_SYSTEM_CLOCK_H_CEIL(hours)
//
// The following macros round down like std::chrono::{floor,duration_cast},
// these are discouraged but sometimes necessary:
//   PW_SYSTEM_CLOCK_MS_FLOOR(milliseconds)
//   PW_SYSTEM_CLOCK_S_FLOOR(seconds)
//   PW_SYSTEM_CLOCK_MIN_FLOOR(minutes)
//   PW_SYSTEM_CLOCK_H_FLOOR(hours)
#include "pw_chrono/internal/system_clock_macros.h"
 
PW_EXTERN_C_START
 
typedef struct {
  int64_t ticks;
} pw_chrono_SystemClock_Duration;
 
typedef struct {
  pw_chrono_SystemClock_Duration duration_since_epoch;
} pw_chrono_SystemClock_TimePoint;
typedef int64_t pw_chrono_SystemClock_Nanoseconds;
 
// Returns the current time, see SystemClock::now() for more detail.
pw_chrono_SystemClock_TimePoint pw_chrono_SystemClock_Now(void);
 
// Returns the change in time between the current_time - last_time.
pw_chrono_SystemClock_Duration pw_chrono_SystemClock_TimeElapsed(
    pw_chrono_SystemClock_TimePoint last_time,
    pw_chrono_SystemClock_TimePoint current_time);
 
// For lossless time unit conversion, the seconds per tick ratio that is
// numerator/denominator should be used:
//   PW_CHRONO_SYSTEM_CLOCK_PERIOD_SECONDS_NUMERATOR
//   PW_CHRONO_SYSTEM_CLOCK_PERIOD_SECONDS_DENOMINATOR
 
// Warning, this may be lossy due to the use of std::chrono::floor,
// rounding towards zero.
pw_chrono_SystemClock_Nanoseconds pw_chrono_SystemClock_DurationToNsFloor(
    pw_chrono_SystemClock_Duration duration);
 
PW_EXTERN_C_END