src/timer/timer.h

   1 /*
   2  * This file is part of OpenTTD.
   3  * OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
   4  * OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   5  * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
   6  */
   7
   8 /** @file timer.h Definition of Interval and OneShot timers */
   9
  10 #ifndef TIMER_H
  11 #define TIMER_H
  12
  13 #include "timer_manager.h"
  14
  15
  16 /**
  17  * The base where every other type of timer is derived from.
  18  *
  19  * Never use this class directly yourself.
  20  */
  21 template <typename TTimerType>
  22 class BaseTimer {
  23 public:
  24         using TPeriod = typename TTimerType::TPeriod;
  25         using TElapsed = typename TTimerType::TElapsed;
  26         using TStorage = typename TTimerType::TStorage;
  27
  28         /**
  29          * Create a new timer.
  30          *
  31          * @param period The period of the timer.
  32          */
  33         [[nodiscard]] BaseTimer(const TPeriod period) :
  34                 period(period)
  35         {
  36                 TimerManager<TTimerType>::RegisterTimer(*this);
  37         }
  38
  39         /**
  40          * Delete the timer.
  41          */
  42         virtual ~BaseTimer()
  43         {
  44                 TimerManager<TTimerType>::UnregisterTimer(*this);
  45         }
  46
  47         /* Although these variables are public, they are only public to make saveload easier; not for common use. */
  48
  49         TPeriod period; ///< The period of the timer.
  50         TStorage storage = {}; ///< The storage of the timer.
  51
  52 protected:
  53         /**
  54          * Called by the timer manager to notify the timer that the given amount of time has elapsed.
  55          *
  56          * @param delta Depending on the time type, this is either in milliseconds or in ticks.
  57          */
  58         virtual void Elapsed(TElapsed delta) = 0;
  59
  60         /* To ensure only TimerManager can access Elapsed. */
  61         friend class TimerManager<TTimerType>;
  62 };
  63
  64 /**
  65  * An interval timer will fire every interval, and will continue to fire until it is deleted.
  66  *
  67  * The callback receives how many times the timer has fired since the last time it fired.
  68  * It will always try to fire every interval, but in times of severe stress it might be late.
  69  *
  70  * Each Timer-type needs to implement the Elapsed() method, and call the callback if needed.
  71  *
  72  * Setting the period to zero disables the interval. It can be reenabled at any time by
  73  * calling SetInterval() with a non-zero period.
  74  */
  75 template <typename TTimerType>
  76 class IntervalTimer : public BaseTimer<TTimerType> {
  77 public:
  78         using TPeriod = typename TTimerType::TPeriod;
  79         using TElapsed = typename TTimerType::TElapsed;
  80
  81         /**
  82          * Create a new interval timer.
  83          *
  84          * @param interval The interval between each callback.
  85          * @param callback The callback to call when the interval has passed.
  86          */
  87         [[nodiscard]] IntervalTimer(const TPeriod interval, std::function<void(uint)> callback) :
  88                 BaseTimer<TTimerType>(interval),
  89                 callback(callback)
  90         {
  91         }
  92
  93         /**
  94          * Set a new interval for the timer.
  95          *
  96          * @param interval The interval between each callback.
  97          * @param reset Whether to reset the timer to zero.
  98          */
  99         void SetInterval(const TPeriod interval, bool reset = true)
 100         {
 101                 TimerManager<TTimerType>::ChangeRegisteredTimerPeriod(*this, interval);
 102                 if (reset) this->storage = {};
 103         }
 104
 105 private:
 106         std::function<void(uint)> callback;
 107
 108         void Elapsed(TElapsed count) override;
 109 };
 110
 111 /**
 112  * A timeout timer will fire once after the interval. You can reset it to fire again.
 113  * The timer will never fire before the interval has passed, but in times of severe stress it might be late.
 114  */
 115 template <typename TTimerType>
 116 class TimeoutTimer : public BaseTimer<TTimerType> {
 117 public:
 118         using TPeriod = typename TTimerType::TPeriod;
 119         using TElapsed = typename TTimerType::TElapsed;
 120
 121         /**
 122          * Create a new timeout timer.
 123          *
 124          * By default the timeout starts aborted; you will have to call Reset() before it starts.
 125          *
 126          * @param timeout The timeout after which the timer will fire.
 127          * @param callback The callback to call when the timeout has passed.
 128          * @param start Whether to start the timer immediately. If false, you can call Reset() to start it.
 129          */
 130         [[nodiscard]] TimeoutTimer(const TPeriod timeout, std::function<void()> callback, bool start = false) :
 131                 BaseTimer<TTimerType>(timeout),
 132                 fired(!start),
 133                 callback(callback)
 134         {
 135         }
 136
 137         /**
 138          * Reset the timer, so it will fire again after the timeout.
 139          */
 140         void Reset()
 141         {
 142                 this->fired = false;
 143                 this->storage = {};
 144         }
 145
 146         /**
 147          * Reset the timer, so it will fire again after the timeout.
 148          *
 149          * @param timeout Set a new timeout for the next trigger.
 150          */
 151         void Reset(const TPeriod timeout)
 152         {
 153                 TimerManager<TTimerType>::ChangeRegisteredTimerPeriod(*this, timeout);
 154                 this->fired = false;
 155                 this->storage = {};
 156         }
 157
 158         /**
 159          * Abort the timer so it doesn't fire if it hasn't yet.
 160          */
 161         void Abort()
 162         {
 163                 this->fired = true;
 164         }
 165
 166         /**
 167          * Check whether the timeout occurred.
 168          *
 169          * @return True iff the timeout occurred.
 170          */
 171         bool HasFired() const
 172         {
 173                 return this->fired;
 174         }
 175
 176         /* Although these variables are public, they are only public to make saveload easier; not for common use. */
 177
 178         bool fired; ///< Whether the timeout has occurred.
 179
 180 private:
 181         std::function<void()> callback;
 182
 183         void Elapsed(TElapsed count) override;
 184 };
 185
 186 #endif /* TIMER_H */