zypp/zyppng/base/timer.h

   1 /*---------------------------------------------------------------------\
   2 |                          ____ _   __ __ ___                          |
   3 |                         |__  / \ / / . \ . \                         |
   4 |                           / / \ V /|  _/  _/                         |
   5 |                          / /__ | | | | | |                           |
   6 |                         /_____||_| |_| |_|                           |
   7 |                                                                      |
   8 \----------------------------------------------------------------------/
   9 *
  10 * This file contains private API, this might break at any time between releases.
  11 * You have been warned!
  12 *
  13 */
  14 #ifndef ZYPP_NG_BASE_TIMER_H_INCLUDED
  15 #define ZYPP_NG_BASE_TIMER_H_INCLUDED
  16
  17 #include <zypp/zyppng/base/zyppglobal.h>
  18 #include <zypp/zyppng/base/Base>
  19 #include <zypp/zyppng/base/Signals>
  20 #include <functional>
  21
  22 namespace zyppng {
  23 class TimerPrivate;
  24 class EventDispatcher;
  25
  26 /*!
  27  * \brief The Timer class provides repetitive and single-shot timers.
  28  *
  29  * Provides a high level interface for timers. To use it, create a Timer and
  30  * connect a slot to its \sa sigExpired signal.
  31  *
  32  * \code
  33  * zyppng::Timer::Ptr t1 = zyppng::Timer::create();
  34  * t1->sigExpired().connect( sigc::mem_fun(this, &HandlerClass::timeout) );
  35  * t1->start(1000);
  36  * \endcode
  37  *
  38  * The timeout slot will now be called every second.
  39  *
  40  * \note The accuracy of the timer should be around 1ms , but also depends on the underlying hardware.
  41  */
  42 class Timer : public Base
  43 {
  44   ZYPP_DECLARE_PRIVATE(Timer)
  45   friend class EventDispatcher;
  46
  47 public:
  48
  49   using Ptr = std::shared_ptr<Timer>;
  50   using WeakPtr = std::shared_ptr<Timer>;
  51
  52   /*!
  53    * \brief Creates a new Timer object, the timer is not started at this point
  54    */
  55   static std::shared_ptr<Timer> create ();
  56   virtual ~Timer ();
  57
  58   /*!
  59    * \brief Sets the timer to trigger only once, after it has expired once
  60    *        \sa start needs to be called again
  61    */
  62   void setSingleShot ( bool singleShot = true );
  63
  64   /*!
  65    * \returns true if the timer is a single shot timer
  66    */
  67   bool singleShot () const;
  68
  69   /*!
  70    * \returns The current monotonic system time in milliseconds
  71    */
  72   static uint64_t now ();
  73
  74   /*!
  75    * \returns the monotonic system time when the timer started
  76    */
  77   uint64_t started  () const;
  78
  79   /*!
  80    * \returns the requested interval in milliseconds
  81    */
  82   uint64_t interval () const;
  83
  84   /*!
  85    * \returns the remaining time until the timer expires in milliseconds
  86    */
  87   uint64_t remaining  () const;
  88
  89   /*!
  90    * \return the time that has elapsed since the last call to \a start in milliseconds
  91    */
  92   uint64_t elapsed  () const;
  93
  94   /*!
  95    * \returns the monotonic system time in ms when the timer is about to expire
  96    */
  97   uint64_t expires () const;
  98
  99   /*!
 100    * \brief Advances the internal clock of the timer, if the timer expires the \a sigExpired signal is emitted
 101    *
 102    * \returns the monotonic system time in ms when the timer is about to expire
 103    * \note There should not be any reason to call this manually, the \sa EventDispatcher is taking care of that
 104    */
 105   uint64_t expire ();
 106
 107   /*!
 108    * \returns if the timer is currently active
 109    */
 110   bool isRunning ( ) const;
 111
 112   /*!
 113    * Starts the timer, if the timer is already running this will restart the currently running timer
 114    */
 115   void start ( );
 116
 117   /*!
 118    * \brief Starts the timer, if the timer is already running this will restart the currently running timer
 119    * \param timeout the new timeout in ms
 120    */
 121   void start ( uint64_t timeout );
 122
 123   /*!
 124    * \brief Stops the timer if its running. The \sa sigExpired signal will not emit until \sa start was called again
 125    */
 126   void stop  ();
 127
 128   /*!
 129    * \brief This signal is always emitted when the timer expires.
 130    */
 131   SignalProxy<void (Timer &t)> sigExpired ();
 132
 133 protected:
 134   Timer ();
 135 };
 136
 137 }
 138
 139 #endif