001/* 002 Licensed to the Apache Software Foundation (ASF) under one 003 or more contributor license agreements. See the NOTICE file 004 distributed with this work for additional information 005 regarding copyright ownership. The ASF licenses this file 006 to you under the Apache License, Version 2.0 (the 007 "License"); you may not use this file except in compliance 008 with the License. You may obtain a copy of the License at 009 010 http://www.apache.org/licenses/LICENSE-2.0 011 012 Unless required by applicable law or agreed to in writing, 013 software distributed under the License is distributed on an 014 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 KIND, either express or implied. See the License for the 016 specific language governing permissions and limitations 017 under the License. 018 */ 019package org.apache.wiki; 020 021import org.apache.logging.log4j.LogManager; 022import org.apache.logging.log4j.Logger; 023import org.apache.wiki.api.core.Engine; 024import org.apache.wiki.util.Synchronizer; 025 026import java.lang.ref.WeakReference; 027import java.util.Iterator; 028import java.util.Map; 029import java.util.Set; 030import java.util.Stack; 031import java.util.concurrent.ConcurrentHashMap; 032import java.util.concurrent.locks.ReentrantLock; 033 034 035/** 036 * WatchDog is a general system watchdog. You can attach any Watchable or a Thread object to it, and it will notify you 037 * if a timeout has been exceeded. 038 * <p> 039 * The notification of the timeouts is done from a separate WatchDog thread, of which there is one per watched thread. 040 * This Thread is named 'WatchDog for XXX', where XXX is your Thread name. 041 * <p> 042 * The suggested method of obtaining a WatchDog is via the static factory method, since it will return you the correct 043 * watchdog for the current thread. However, we do not prevent you from creating your own watchdogs either. 044 * <p> 045 * If you create a WatchDog for a Thread, the WatchDog will figure out when the Thread is dead, and will stop itself 046 * accordingly. However, this object is not automatically released, so you might want to check it out after a while. 047 * 048 * @since 2.4.92 049 */ 050public final class WatchDog { 051 052 private final Watchable m_watchable; 053 private final Stack< State > m_stateStack = new Stack<>(); 054 private boolean m_enabled = true; 055 private final Engine m_engine; 056 057 private static final Logger LOG = LogManager.getLogger( WatchDog.class ); 058 059 private static final Map< Integer, WeakReference< WatchDog > > c_kennel = new ConcurrentHashMap<>(); 060 private static WikiBackgroundThread c_watcherThread; 061 062 /** 063 * A lock used to ensure thread safety when accessing shared resources. 064 * This lock provides more flexibility and capabilities than the intrinsic locking mechanism, 065 * such as the ability to attempt to acquire a lock with a timeout, or to interrupt a thread 066 * waiting to acquire a lock. 067 * 068 * @see java.util.concurrent.locks.ReentrantLock 069 */ 070 private final ReentrantLock watchDogLock = new ReentrantLock(); 071 private final ReentrantLock stateStackLock = new ReentrantLock(); 072 073 /** 074 * Returns the current watchdog for the current thread. This is the preferred method of getting you a Watchdog, since it 075 * keeps an internal list of Watchdogs for you so that there won't be more than one watchdog per thread. 076 * 077 * @param engine The Engine to which the Watchdog should be bonded to. 078 * @return A usable WatchDog object. 079 */ 080 public static WatchDog getCurrentWatchDog( final Engine engine ) { 081 final Thread t = Thread.currentThread(); 082 083 WeakReference< WatchDog > w = c_kennel.get( t.hashCode() ); 084 WatchDog wd = null; 085 if( w != null ) { 086 wd = w.get(); 087 } 088 089 if( w == null || wd == null ) { 090 wd = new WatchDog( engine, t ); 091 w = new WeakReference<>( wd ); 092 c_kennel.put( t.hashCode(), w ); 093 } 094 095 return wd; 096 } 097 098 /** 099 * Creates a new WatchDog for a Watchable. 100 * 101 * @param engine The Engine. 102 * @param watch A Watchable object. 103 */ 104 public WatchDog( final Engine engine, final Watchable watch ) { 105 m_engine = engine; 106 m_watchable = watch; 107 108 Synchronizer.synchronize(watchDogLock, () -> { 109 if (c_watcherThread == null) { 110 c_watcherThread = new WatchDogThread(engine); 111 c_watcherThread.start(); 112 } 113 }); 114 } 115 116 /** 117 * Creates a new WatchDog for a Thread. The Thread is wrapped in a Watchable wrapper for this purpose. 118 * 119 * @param engine The Engine 120 * @param thread A Thread for watching. 121 */ 122 public WatchDog( final Engine engine, final Thread thread ) { 123 this( engine, new ThreadWrapper( thread ) ); 124 } 125 126 /** 127 * Hopefully finalizes this properly. This is rather untested for now... 128 */ 129 private static void scrub() { 130 // During finalization, the object may already be cleared (depending on the finalization order). Therefore, it's 131 // possible that this method is called from another thread after the WatchDog itself has been cleared. 132 if( c_kennel.isEmpty() ) { 133 return; 134 } 135 136 for( final Map.Entry< Integer, WeakReference< WatchDog > > e : c_kennel.entrySet() ) { 137 final WeakReference< WatchDog > w = e.getValue(); 138 139 // Remove expired as well 140 if( w.get() == null ) { 141 c_kennel.remove( e.getKey() ); 142 scrub(); 143 break; 144 } 145 } 146 } 147 148 /** 149 * Can be used to enable the WatchDog. Will cause a new Thread to be created, if none was existing previously. 150 */ 151 public void enable() { 152 Synchronizer.synchronize( watchDogLock, () -> { 153 if( !m_enabled ) { 154 m_enabled = true; 155 c_watcherThread = new WatchDogThread( m_engine ); 156 c_watcherThread.start(); 157 } 158 } ); 159 } 160 161 /** 162 * Is used to disable a WatchDog. The watchdog thread is shut down and resources released. 163 */ 164 public void disable() { 165 Synchronizer.synchronize( watchDogLock, () -> { 166 if( m_enabled ) { 167 m_enabled = false; 168 c_watcherThread.shutdown(); 169 c_watcherThread = null; 170 } 171 } ); 172 } 173 174 /** 175 * Enters a watched state with no expectation of the expected completion time. In practice this method is 176 * used when you have no idea, but would like to figure out, e.g. via debugging, where exactly your Watchable is. 177 * 178 * @param state A free-form string description of your state. 179 */ 180 public void enterState( final String state ) { 181 enterState( state, Integer.MAX_VALUE ); 182 } 183 184 /** 185 * Enters a watched state which has an expected completion time. This is the main method for using the 186 * WatchDog. For example: 187 * <code> 188 * WatchDog w = m_engine.getCurrentWatchDog(); 189 * w.enterState("Processing Foobar", 60); 190 * foobar(); 191 * w.exitState(); 192 * </code> 193 * If the call to foobar() takes more than 60 seconds, you will receive an ERROR in the log stream. 194 * 195 * @param state A free-form string description of the state 196 * @param expectedCompletionTime The timeout in seconds. 197 */ 198 public void enterState( final String state, final int expectedCompletionTime ) { 199 LOG.debug( "{}: Entering state {}, expected completion in {} s", m_watchable.getName(), state, expectedCompletionTime ); 200 Synchronizer.synchronize( stateStackLock, () -> { 201 final State st = new State( state, expectedCompletionTime ); 202 m_stateStack.push( st ); 203 } ); 204 } 205 206 /** 207 * Exits a state entered with enterState(). This method does not check that the state is correct, it'll just 208 * pop out whatever is on the top of the state stack. 209 */ 210 public void exitState() { 211 exitState( null ); 212 } 213 214 /** 215 * Exits a particular state entered with enterState(). The state is checked against the current state, and if 216 * they do not match, an error is flagged. 217 * 218 * @param state The state you wish to exit. 219 */ 220 public void exitState( final String state ) { 221 if( !m_stateStack.empty() ) { 222 Synchronizer.synchronize( stateStackLock, () -> { 223 final State st = m_stateStack.peek(); 224 if( state == null || st.getState().equals( state ) ) { 225 m_stateStack.pop(); 226 227 LOG.debug( "{}: Exiting state {}", m_watchable.getName(), st.getState() ); 228 } else { 229 // FIXME: should actually go and fix things for that 230 LOG.error( "exitState() called before enterState()" ); 231 } 232 } ); 233 } else { 234 LOG.warn( "Stack for " + m_watchable.getName() + " is empty!" ); 235 } 236 } 237 238 /** 239 * helper to see if the associated stateStack is not empty. 240 * 241 * @return {@code true} if not empty, {@code false} otherwise. 242 */ 243 public boolean isStateStackNotEmpty() { 244 return !m_stateStack.isEmpty(); 245 } 246 247 /** 248 * helper to see if the associated watchable is alive. 249 * 250 * @return {@code true} if it's alive, {@code false} otherwise. 251 */ 252 public boolean isWatchableAlive() { 253 return m_watchable != null && m_watchable.isAlive(); 254 } 255 256 private void check() { 257 LOG.debug( "Checking watchdog '{}'", m_watchable.getName() ); 258 Synchronizer.synchronize( stateStackLock, () -> { 259 if( !m_stateStack.empty() ) { 260 final State st = m_stateStack.peek(); 261 final long now = System.currentTimeMillis(); 262 263 if( now > st.getExpiryTime() ) { 264 LOG.info( "Watchable '" + m_watchable.getName() + "' exceeded timeout in state '" + st.getState() + 265 "' by " + ( now - st.getExpiryTime() ) / 1_000 + " seconds" + 266 ( LOG.isDebugEnabled() ? "" : "Enable DEBUG-level logging to see stack traces." ) ); 267 dumpStackTraceForWatchable(); 268 269 m_watchable.timeoutExceeded( st.getState() ); 270 } 271 } else { 272 LOG.warn( "Stack for " + m_watchable.getName() + " is empty!" ); 273 } 274 } ); 275 } 276 277 /** 278 * Dumps the stack traces as DEBUG level events. 279 */ 280 private void dumpStackTraceForWatchable() { 281 if( !LOG.isDebugEnabled() ) { 282 return; 283 } 284 285 final Map< Thread, StackTraceElement[] > stackTraces = Thread.getAllStackTraces(); 286 final Set< Thread > threads = stackTraces.keySet(); 287 final Iterator< Thread > threadIterator = threads.iterator(); 288 final StringBuilder stacktrace = new StringBuilder(); 289 290 while ( threadIterator.hasNext() ) { 291 final Thread t = threadIterator.next(); 292 if( t.getName().equals( m_watchable.getName() ) ) { 293 if( t.getName().equals( m_watchable.getName() ) ) { 294 stacktrace.append( "dumping stacktrace for too long running thread : " ).append( t ); 295 } else { 296 stacktrace.append( "dumping stacktrace for other running thread : " ).append( t ); 297 } 298 final StackTraceElement[] ste = stackTraces.get( t ); 299 for( final StackTraceElement stackTraceElement : ste ) { 300 stacktrace.append( "\n" ).append( stackTraceElement ); 301 } 302 } 303 } 304 305 LOG.debug( stacktrace.toString() ); 306 } 307 308 /** 309 * Strictly for debugging/informative purposes. 310 * 311 * @return Random ramblings. 312 */ 313 @Override 314 public String toString() { 315 return Synchronizer.synchronize( stateStackLock, () -> { 316 String state = "Idle"; 317 318 if( !m_stateStack.empty() ) { 319 final State st = m_stateStack.peek(); 320 state = st.getState(); 321 } 322 return "WatchDog state=" + state; 323 } ); 324 } 325 326 /** 327 * This is the chief watchdog thread. 328 */ 329 private static class WatchDogThread extends WikiBackgroundThread { 330 /** How often the watchdog thread should wake up (in seconds) */ 331 private static final int CHECK_INTERVAL = 30; 332 333 public WatchDogThread( final Engine engine ) { 334 super( engine, CHECK_INTERVAL ); 335 setName( "WatchDog for '" + engine.getApplicationName() + "'" ); 336 } 337 338 @Override 339 public void startupTask() { 340 } 341 342 @Override 343 public void shutdownTask() { 344 WatchDog.scrub(); 345 } 346 347 /** 348 * Checks if the watchable is alive, and if it is, checks if the stack is finished. 349 * If the watchable has been deleted in the meantime, will simply shut down itself. 350 */ 351 @Override 352 public void backgroundTask() { 353 if( c_kennel.isEmpty() ) { 354 return; 355 } 356 357 for( final Map.Entry< Integer, WeakReference< WatchDog > > entry : c_kennel.entrySet() ) { 358 final WeakReference< WatchDog > wr = entry.getValue(); 359 final WatchDog w = wr.get(); 360 if( w != null ) { 361 if( w.isWatchableAlive() && w.isStateStackNotEmpty() ) { 362 w.check(); 363 } else { 364 c_kennel.remove( entry.getKey() ); 365 break; 366 } 367 } 368 } 369 370 WatchDog.scrub(); 371 } 372 373 } 374 375 /** 376 * A class which just stores the state in our State stack. 377 */ 378 private static class State { 379 380 protected final String m_state; 381 protected final long m_enterTime; 382 protected final long m_expiryTime; 383 384 protected State( final String state, final int expiry ) { 385 m_state = state; 386 m_enterTime = System.currentTimeMillis(); 387 m_expiryTime = m_enterTime + ( expiry * 1_000L ); 388 } 389 390 protected String getState() { 391 return m_state; 392 } 393 394 protected long getExpiryTime() { 395 return m_expiryTime; 396 } 397 398 } 399 400 /** 401 * This class wraps a Thread so that it can become Watchable. 402 */ 403 private static class ThreadWrapper implements Watchable { 404 private final Thread m_thread; 405 406 public ThreadWrapper( final Thread thread ) { 407 m_thread = thread; 408 } 409 410 @Override 411 public void timeoutExceeded( final String state ) { 412 // TODO: Figure out something sane to do here. 413 } 414 415 @Override 416 public String getName() { 417 return m_thread.getName(); 418 } 419 420 @Override 421 public boolean isAlive() { 422 return m_thread.isAlive(); 423 } 424 } 425 426}