1 /*
2 Copyright 2008 Ramon Servadei
3
4 Licensed under the Apache License, Version 2.0 (the "License");
5 you may not use this file except in compliance with the License.
6 You may obtain a copy of the License at
7
8 http://www.apache.org/licenses/LICENSE-2.0
9
10 Unless required by applicable law or agreed to in writing, software
11 distributed under the License is distributed on an "AS IS" BASIS,
12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 See the License for the specific language governing permissions and
14 limitations under the License.
15 */
16 package fulmine.context;
17
18 import fulmine.distribution.connection.AbstractConnectionDiscoverer;
19
20 /**
21 * A component that monitors the state of an {@link IFrameworkContext}. This
22 * reports whether the context is healthy and is typically queried by an
23 * {@link AbstractConnectionDiscoverer} before sending out a heartbeat. The
24 * {@link #isContextHealthy()} method is invoked each time to determine if a
25 * heartbeat should be sent out. This mechanism allows application code to
26 * effectively disconnect the context from other contexts as it will miss the
27 * allowed number of heartbeats.
28 * <p>
29 * On each heartbeat, this component is also informed whether the system is
30 * operating as normal or is suffering from resource/thread starvation. The
31 * resource/thread status is reported generally by measuring the expected
32 * heartbeat period against the actual period.
33 *
34 * @author Ramon Servadei
35 */
36 public interface IContextWatchdog
37 {
38 /**
39 * Indicates whether the {@link IFrameworkContext} is healthy or not.
40 * Reasons why it may not be healthy are:
41 * <ul>
42 * <li>a thread deadlock <li>a resource is unavailable <li>thread starvation
43 * </ul>
44 *
45 * @return <code>true</code> if the context is healthy and a heartbeat
46 * should be sent out, <code>false</code> otherwise.
47 */
48 boolean isContextHealthy();
49
50 /**
51 * Informs this component that the context is low on CPU resource; there is
52 * some form of CPU time/resource starvation occurring for the context
53 * threads.
54 * <p>
55 * This is not an absolute indication, it is called every time the heartbeat
56 * period is exceeded by the {@link AbstractConnectionDiscoverer}.
57 *
58 * @see IContextWatchdog#systemNormal()
59 */
60 void cpuResourcesLow();
61
62 /**
63 * Informs this component that the context is operating as normal and
64 * heartbeats are being broadcasted at the required period.
65 *
66 * @see IContextWatchdog#cpuResourcesLow()
67 */
68 void systemNormal();
69 }