Open Lighting Architecture  Latest Git
HealthCheckedConnection.h
1 /*
2  * This library is free software; you can redistribute it and/or
3  * modify it under the terms of the GNU Lesser General Public
4  * License as published by the Free Software Foundation; either
5  * version 2.1 of the License, or (at your option) any later version.
6  *
7  * This library is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
10  * Lesser General Public License for more details.
11  *
12  * You should have received a copy of the GNU Lesser General Public
13  * License along with this library; if not, write to the Free Software
14  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
15  *
16  * HealthCheckedConnection.h
17  * Copyright (C) 2012 Simon Newton
18  *
19  * This class adds health checking to a connection, which ensures that the
20  * connection is able to transfer data in a timely manner. The implementation
21  * is pretty simple: we define a heart beat interval I, which *must* be the
22  * same at both ends of the connection. Every I seconds, both ends send a
23  * heart beat message and if either end doesn't receive a heart beat in
24  * 2.5 * I, the connection is deemed dead, and the connection is closed.
25  *
26  * This class provides the basic health check mechanism, the sub class is left
27  * to define the format of the heartbeat message.
28  *
29  * To use this health checked channel, subclass HealthCheckedConnection, and
30  * provide the SendHeartbeat() and HeartbeatTimeout methods.
31  *
32  * There are some additional features:
33  * - Some receivers may want to stop reading from a connection under some
34  * circumstances (e.g. flow control). Before this happens, call PauseTimer()
35  * to pause the rx timer, otherwise the channel will be marked unhealthy. Once
36  * reading is resumed called ResumeTimer();
37  * - Some protocols may want to piggyback heartbeats on other messages, or
38  * even count any message as a heartbeat. When such a message is received, be
39  * sure to call HeartbeatReceived() which will update the timer.
40  */
41 
42 #ifndef INCLUDE_OLA_NETWORK_HEALTHCHECKEDCONNECTION_H_
43 #define INCLUDE_OLA_NETWORK_HEALTHCHECKEDCONNECTION_H_
44 
45 #include <ola/Callback.h>
46 #include <ola/Clock.h>
47 #include <ola/base/Macro.h>
48 #include <ola/thread/SchedulerInterface.h>
49 
50 namespace ola {
51 namespace network {
52 
58  public:
60  const ola::TimeInterval timeout_interval);
61  virtual ~HealthCheckedConnection();
62 
66  bool Setup();
67 
68  // Sending methods
69  //-----------------------------
70 
71  /*
72  * Subclasses implement this to send a health check
73  */
74  virtual void SendHeartbeat() = 0;
75 
80  void HeartbeatSent();
81 
82 
83  // Receiving methods
84  //-----------------------------
85 
86  // Call this method every time a valid health check is received.
87  void HeartbeatReceived();
88 
89  /*
90  * This pauses the timer which checks for heartbeats. Call this if you stop
91  * reading from the socket for any reason.
92  */
93  void PauseTimer();
94 
98  void ResumeTimer();
99 
100  protected:
104  virtual void HeartbeatTimeout() = 0;
105 
106  private:
107  ola::thread::SchedulerInterface *m_scheduler;
108  ola::TimeInterval m_heartbeat_interval;
109  ola::thread::timeout_id m_send_timeout_id;
110  ola::thread::timeout_id m_receive_timeout_id;
111 
112  bool SendNextHeartbeat();
113  void UpdateReceiveTimer();
114  void InternalHeartbeatTimeout();
115 
116  DISALLOW_COPY_AND_ASSIGN(HealthCheckedConnection);
117 };
118 } // namespace network
119 } // namespace ola
120 #endif // INCLUDE_OLA_NETWORK_HEALTHCHECKEDCONNECTION_H__
A time interval, with usecond accuracy.
Definition: Clock.h:138
Definition: HealthCheckedConnection.h:57
bool Setup()
Definition: HealthCheckedConnection.cpp:45
void PauseTimer()
Definition: HealthCheckedConnection.cpp:80
void ResumeTimer()
Definition: HealthCheckedConnection.cpp:91
void * timeout_id
A timeout handle which can later be used to cancel a timeout.
Definition: SchedulerInterface.h:34
void HeartbeatSent()
Definition: HealthCheckedConnection.cpp:59
Helper macros.
The namespace containing all OLA symbols.
Definition: Credentials.cpp:44
Allows Callbacks to be scheduled to run after a specified interval.
Definition: SchedulerInterface.h:46
void HeartbeatReceived()
Definition: HealthCheckedConnection.cpp:71