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}