Open Lighting Architecture  0.9.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 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/thread/SchedulerInterface.h>
48 
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 
103  virtual void HeartbeatTimeout() = 0;
104 
105  private:
106  ola::thread::SchedulerInterface *m_scheduler;
107  ola::TimeInterval m_heartbeat_interval;
108  ola::thread::timeout_id m_send_timeout_id;
109  ola::thread::timeout_id m_receive_timeout_id;
110 
111  bool SendNextHeartbeat();
112  void UpdateReceiveTimer();
113 };
114 } // namespace network
115 } // namespace ola
116 #endif // INCLUDE_OLA_NETWORK_HEALTHCHECKEDCONNECTION_H__