1 // Copyright (c) 2009 The Chromium Authors. All rights reserved.

     2 // Use of this source code is governed by a BSD-style license that can be

     3 // found in the LICENSE file.

     4 

     5 package org.chromium.sdk.internal.tools.v8;

     6 

     7 /**

     8  * Signals that a deadlock was about to happen.

     9  * <p>

    10  * Method may wait for some callback to receive a result from some worker

    11  * thread. If this method happened to be called from another callback

    12  * being run by the same thread this will block the thread forever because

    13  * method is never going to get result. Such situation may raise this

    14  * exception.

    15  * <p>

    16  * Currently this exception is never actually thrown so it gets more of

    17  * symbolic sense. Nevertheless it's still important to keep its declaration

    18  * because it helps to track which ones are blocking and which are not.

    19  * To do this, one should temporary modify this class and make exception checked

    20  * (make it extend {@code java.lang.Exception}). This will enforce the proper

    21  * declaration of all blocking methods.

    22  * <p>Here are the simple rules: you never normally catch this exception, but

    23  * add throws declaration wherever needed; if your callback method needs to

    24  * throw it you are doing something wrong (i.e. calling blocking method from

    25  * a callback) and risk running into a deadlock; wherever you are

    26  * sure you are on a safe ground (not called from callback) and there is no

    27  * need in further tracking this exception, make a symbolic try/catch and

    28  * explain why you think it's safe, in a catch block:

    29  * <pre>

    30  *   try {

    31  *     makeSureAllScriptsAreLoaded();

    32  *   } catch (MethodIsBlockingException e) {

    33  *     // I'm being called from my own thread, so it's ok if method blocks,

    34  *     // I can wait

    35  *     throw new RuntimeException(e); // never executed

    36  *   }

    37  * </pre>

    38  * <p>By default, {@code MethodIsBlockingException} is unchecked exception,

    39  * so you may completely ignore it.

    40  */

    41 public class MethodIsBlockingException extends RuntimeException {

    42   // We never actually instantiate this exception, because it's symbolic.

    43   private MethodIsBlockingException() {}

    44 }