nucleus/library/processes/heartbeat.h

   1 #ifndef HEARTBEAT_CLASS
   2 #define HEARTBEAT_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : heartbeat                                                         *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 1996-$now By Author.  This program is free software; you can  *
  11 * redistribute it and/or modify it under the terms of the GNU General Public  *
  12 * License as published by the Free Software Foundation; either version 2 of   *
  13 * the License or (at your option) any later version.  This is online at:      *
  14 *     http://www.fsf.org/copyleft/gpl.html                                    *
  15 * Please send any updates to: fred@gruntose.com                               *
  16 \*****************************************************************************/
  17
  18 #include <basis/astring.h>
  19 #include <basis/contracts.h>
  20 #include <timely/time_stamp.h>
  21
  22 namespace processes {
  23
  24 //! Monitors a periodic heartbeat to track a resource's health.
  25 /*!
  26   The heartbeat is defined as a "request-and-response" based check; when the
  27   next periodic heartbeat is due, a request is sent out.  The heartbeat
  28   request is considered successfully dealt with only if a response comes back
  29   for the request.  If the user-defined number of requests are sent without
  30   a single response coming back, then the 'patient' is considered dead.
  31 */
  32
  33 class heartbeat : public virtual basis::root_object
  34 {
  35 public:
  36   heartbeat(int misses_allowed = 500, int check_interval = 10000);
  37     //!< creates a heartbeat monitor with the specified interval and maximum skips permitted.
  38     /*!< this allows the heartbeat request to be missed "misses_allowed" times.
  39     the heartbeats will become due every "check_interval" milliseconds.  the
  40     defaults are a joke; you really need to set them. */
  41   heartbeat(const heartbeat &to_copy);
  42
  43   ~heartbeat();
  44
  45   DEFINE_CLASS_NAME("heartbeat");
  46
  47   heartbeat &operator =(const heartbeat &to_copy);
  48
  49   basis::astring text_form(bool detailed = false) const;
  50     //!< returns a readable form of the heartbeat's information.
  51
  52   void reset(int misses_allowed, int check_interval);
  53     //!< retrains the heartbeat monitor for a new configuration.
  54
  55   bool due() const;
  56     //!< is the next heartbeat due yet?
  57
  58   bool dead() const;
  59     //!< is this object considered dead from missing too many heartbeats?
  60     /*!< this is true if the heartbeat being monitored missed too many
  61     responses to heartbeat requests.  if the maximum allowed requests have
  62     been made and there was not even a single response, then the object is
  63     considered dead. */
  64
  65   void made_request();
  66     //!< records that another heartbeat request was sent out.
  67     /*!< the time for the next heartbeat request is reset to the time between
  68     beats.  if there were already the maximum allowed number of missed
  69     responses, then the object is now dead. */
  70   void need_beat() { made_request(); }
  71     //!< a synonym for the made_request() method.
  72
  73   void kabump();
  74     //!< registers a heartbeat response and sets the state to healthy.
  75     /*!< this records that a heartbeat response came back from the monitored
  76     object.  after this call, there are no heartbeats recorded as missed at
  77     all. */
  78   void recycle() { kabump(); }
  79     //!< a synonym for kabump().
  80
  81   // reporting functions for internal state...
  82
  83   int missed_so_far() const { return _misses; }
  84     //!< returns the number of heartbeat responses that are pending.
  85   int misses_left() const { return _misses_allowed - _misses; }
  86     //!< the number of misses that this object is still allowed.
  87
  88   int allowed_misses() const { return _misses_allowed; }
  89     //!< returns the number of misses allowed overall.
  90   int checking_interval() const { return _check_interval; }
  91     //!< returns the period of the heartbeats.
  92
  93   timely::time_stamp heartbeat_time() const;
  94     //!< returns the time when the next heartbeat will be requested.
  95     /*!< if no heartbeats had been missed yet, then this is the time when
  96     the due() method starts returning true. */
  97
  98   int time_left() const;
  99     //!< number of milliseconds left before the next beat will be requested.
 100     /*!< if the number is zero or negative, then a heartbeat is due. */
 101
 102 private:
 103   timely::time_stamp *_next_heartbeat;
 104   int _check_interval;
 105   int _misses_allowed;
 106   int _misses;
 107
 108   void reset_next_beat();  //!< resets the next_heartbeat to our interval.
 109 };
 110
 111 } //namespace.
 112
 113 #endif
 114