fuchsia / third_party / openthread / d9dd34ea6fed895c3fc7902f4739ee9a032e6d6e / . / src / core / common / time.hpp

/* | |

* Copyright (c) 2019, The OpenThread Authors. | |

* All rights reserved. | |

* | |

* Redistribution and use in source and binary forms, with or without | |

* modification, are permitted provided that the following conditions are met: | |

* 1. Redistributions of source code must retain the above copyright | |

* notice, this list of conditions and the following disclaimer. | |

* 2. Redistributions in binary form must reproduce the above copyright | |

* notice, this list of conditions and the following disclaimer in the | |

* documentation and/or other materials provided with the distribution. | |

* 3. Neither the name of the copyright holder nor the | |

* names of its contributors may be used to endorse or promote products | |

* derived from this software without specific prior written permission. | |

* | |

* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" | |

* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |

* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |

* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE | |

* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR | |

* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF | |

* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS | |

* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN | |

* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) | |

* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE | |

* POSSIBILITY OF SUCH DAMAGE. | |

*/ | |

/** | |

* @file | |

* This file includes definitions for time instance. | |

*/ | |

#ifndef TIME_HPP_ | |

#define TIME_HPP_ | |

#include "openthread-core-config.h" | |

#include <stddef.h> | |

#include <stdint.h> | |

#include "common/equatable.hpp" | |

#include "common/serial_number.hpp" | |

namespace ot { | |

/** | |

* @addtogroup core-timer | |

* | |

* @brief | |

* This module includes definitions for the time instance. | |

* | |

* @{ | |

* | |

*/ | |

/** | |

* This class represents a time instance. | |

* | |

*/ | |

class Time : public Unequatable<Time> | |

{ | |

public: | |

static constexpr uint32_t kOneSecondInMsec = 1000u; ///< One second interval in msec. | |

static constexpr uint32_t kOneMinuteInMsec = kOneSecondInMsec * 60; ///< One minute interval in msec. | |

static constexpr uint32_t kOneHourInMsec = kOneMinuteInMsec * 60; ///< One hour interval in msec. | |

static constexpr uint32_t kOneDayInMsec = kOneHourInMsec * 24; ///< One day interval in msec. | |

/** | |

* This constant defines a maximum time duration ensured to be longer than any other duration. | |

* | |

*/ | |

static const uint32_t kMaxDuration = ~static_cast<uint32_t>(0UL); | |

/** | |

* This is the default constructor for a `Time` object. | |

* | |

*/ | |

Time(void) = default; | |

/** | |

* This constructor initializes a `Time` object with a given value. | |

* | |

* @param[in] aValue The numeric time value to initialize the `Time` object. | |

* | |

*/ | |

explicit Time(uint32_t aValue) { SetValue(aValue); } | |

/** | |

* This method gets the numeric time value associated with the `Time` object. | |

* | |

* @returns The numeric `Time` value. | |

* | |

*/ | |

uint32_t GetValue(void) const { return mValue; } | |

/** | |

* This method sets the numeric time value. | |

* | |

* @param[in] aValue The numeric time value. | |

* | |

*/ | |

void SetValue(uint32_t aValue) { mValue = aValue; } | |

/** | |

* This method calculates the time duration between two `Time` instances. | |

* | |

* @note Expression `(t1 - t2)` returns the duration of the interval starting from `t2` and ending at `t1`. When | |

* calculating the duration, `t2 is assumed to be in the past relative to `t1`. The duration calculation correctly | |

* takes into account the wrapping of numeric value of `Time` instances. The returned value can span the entire | |

* range of the `uint32_t` type. | |

* | |

* @param[in] aOther A `Time` instance to subtract from. | |

* | |

* @returns The duration of interval from @p aOther to this `Time` object. | |

* | |

*/ | |

uint32_t operator-(const Time &aOther) const { return mValue - aOther.mValue; } | |

/** | |

* This method returns a new `Time` which is ahead of this `Time` object by a given duration. | |

* | |

* @param[in] aDuration A duration. | |

* | |

* @returns A new `Time` which is ahead of this object by @aDuration. | |

* | |

*/ | |

Time operator+(uint32_t aDuration) const { return Time(mValue + aDuration); } | |

/** | |

* This method returns a new `Time` which is behind this `Time` object by a given duration. | |

* | |

* @param[in] aDuration A duration. | |

* | |

* @returns A new `Time` which is behind this object by @aDuration. | |

* | |

*/ | |

Time operator-(uint32_t aDuration) const { return Time(mValue - aDuration); } | |

/** | |

* This method moves this `Time` object forward by a given duration. | |

* | |

* @param[in] aDuration A duration. | |

* | |

*/ | |

void operator+=(uint32_t aDuration) { mValue += aDuration; } | |

/** | |

* This method moves this `Time` object backward by a given duration. | |

* | |

* @param[in] aDuration A duration. | |

* | |

*/ | |

void operator-=(uint32_t aDuration) { mValue -= aDuration; } | |

/** | |

* This method indicates whether two `Time` instances are equal. | |

* | |

* @param[in] aOther A `Time` instance to compare with. | |

* | |

* @retval TRUE The two `Time` instances are equal. | |

* @retval FALSE The two `Time` instances are not equal. | |

* | |

*/ | |

bool operator==(const Time &aOther) const { return mValue == aOther.mValue; } | |

/** | |

* This method indicates whether this `Time` instance is strictly before another one. | |

* | |

* @note The comparison operators correctly take into account the wrapping of `Time` numeric value. For a given | |

* `Time` instance `t0`, any `Time` instance `t` where `(t - t0)` is less than half the range of `uint32_t` type | |

* is considered to be after `t0`, otherwise it is considered to be before 't0' (or equal to it). As an example | |

* to illustrate this model we can use clock hours: If we are at hour 12, hours 1 to 5 are considered to be | |

* after 12, and hours 6 to 11 are considered to be before 12. | |

* | |

* @param[in] aOther A `Time` instance to compare with. | |

* | |

* @retval TRUE This `Time` instance is strictly before @p aOther. | |

* @retval FALSE This `Time` instance is not strictly before @p aOther. | |

* | |

*/ | |

bool operator<(const Time &aOther) const { return SerialNumber::IsLess(mValue, aOther.mValue); } | |

/** | |

* This method indicates whether this `Time` instance is after or equal to another one. | |

* | |

* @param[in] aOther A `Time` instance to compare with. | |

* | |

* @retval TRUE This `Time` instance is after or equal to @p aOther. | |

* @retval FALSE This `Time` instance is not after or equal to @p aOther. | |

* | |

*/ | |

bool operator>=(const Time &aOther) const { return !(*this < aOther); } | |

/** | |

* This method indicates whether this `Time` instance is before or equal to another one. | |

* | |

* @param[in] aOther A `Time` instance to compare with. | |

* | |

* @retval TRUE This `Time` instance is before or equal to @p aOther. | |

* @retval FALSE This `Time` instance is not before or equal to @p aOther. | |

* | |

*/ | |

bool operator<=(const Time &aOther) const { return (aOther >= *this); } | |

/** | |

* This method indicates whether this `Time` instance is strictly after another one. | |

* | |

* @param[in] aOther A `Time` instance to compare with. | |

* | |

* @retval TRUE This `Time` instance is strictly after @p aOther. | |

* @retval FALSE This `Time` instance is not strictly after @p aOther. | |

* | |

*/ | |

bool operator>(const Time &aOther) const { return (aOther < *this); } | |

/** | |

* This method returns a new `Time` instance which is in distant future relative to current `Time` object. | |

* | |

* The returned distance future `Time` is guaranteed to be equal or after (as defined by comparison operator `<=`) | |

* any other `Time` which is after this `Time` object, i.e., for any `t` for which we have `*this <= t`, it is | |

* ensured that `t <= this->GetGetDistantFuture()`. | |

* | |

* @returns A new `Time` in distance future relative to current `Time` object. | |

* | |

*/ | |

Time GetDistantFuture(void) const { return Time(mValue + kDistantFuture); } | |

/** | |

* This method returns a new `Time` instance which is in distant past relative to current `Time` object. | |

* | |

* The returned distance past `Time` is guaranteed to be equal or before (as defined by comparison operator `>=`) | |

* any other `Time` which is before this `Time` object, i.e., for any `t` for which we have `*this >= t`, it is | |

* ensured that `t >= this->GetDistantPast()`. | |

* | |

* @returns A new `Time` in distance past relative to current `Time` object. | |

* | |

*/ | |

Time GetDistantPast(void) const { return Time(mValue - kDistantFuture); } | |

/** | |

* This static method converts a given number of seconds to milliseconds. | |

* | |

* @param[in] aSeconds The seconds value to convert to milliseconds. | |

* | |

* @returns The number of milliseconds. | |

* | |

*/ | |

static uint32_t constexpr SecToMsec(uint32_t aSeconds) { return aSeconds * 1000u; } | |

/** | |

* This static method converts a given number of milliseconds to seconds. | |

* | |

* @param[in] aMilliseconds The milliseconds value to convert to seconds. | |

* | |

* @returns The number of seconds. | |

* | |

*/ | |

static uint32_t constexpr MsecToSec(uint32_t aMilliseconds) { return aMilliseconds / 1000u; } | |

private: | |

static constexpr uint32_t kDistantFuture = (1UL << 31); | |

uint32_t mValue; | |

}; | |

/** | |

* This type represents a time instance (millisecond time). | |

* | |

*/ | |

typedef Time TimeMilli; | |

#if OPENTHREAD_CONFIG_PLATFORM_USEC_TIMER_ENABLE | |

/** | |

* This type represents a time instance (microsecond time). | |

* | |

*/ | |

typedef Time TimeMicro; | |

#endif // OPENTHREAD_CONFIG_PLATFORM_USEC_TIMER_ENABLE | |

/** | |

* @} | |

* | |

*/ | |

} // namespace ot | |

#endif // TIME_HPP_ |