ExitUtil (Apache Hadoop Common 3.5.0 API)
Description: declaration: package: org.apache.hadoop.util, class: ExitUtil

Package org.apache.hadoop.util

# Class ExitUtil

java.lang.Object
org.apache.hadoop.util.ExitUtil

@LimitedPrivate({"HDFS","MapReduce","YARN"}) @Unstable public final class ExitUtil extends Object
Facilitates hooking process termination for tests, debugging and embedding. Hadoop code that attempts to call `System.exit(int)` or `Runtime.halt(int)` MUST invoke it via these methods.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `ExitUtil.ExitException`
  An exception raised when a call to `terminate(int)` was called and system exits were blocked.
  `static class`
  `ExitUtil.HaltException`
  An exception raised when a call to `terminate(int)` was called and system halts were blocked.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `EXIT_EXCEPTION_MESSAGE`
  Message raised from an exit exception if none were provided: "ExitException".
  `static final String`
  `HALT_EXCEPTION_MESSAGE`
  Message raised from a halt exception if none were provided: "HaltException".

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `disableSystemExit()`
  Disable the use of System.exit for testing.
  `static void`
  `disableSystemHalt()`
  Disable the use of `Runtime.getRuntime().halt()` for testing.
  `static void`
  `enableSystemExit()`
  Enable the use of System.exit for testing.
  `static ExitUtil.ExitException`
  `getFirstExitException()`
  `static ExitUtil.HaltException`
  `getFirstHaltException()`
  `static void`
  `halt(int status)`
  Forcibly terminates the currently running Java virtual machine.
  `static void`
  `halt(int status, String message)`
  Forcibly terminates the currently running Java virtual machine.
  `static void`
  `halt(int status, Throwable t)`
  Forcibly terminates the currently running Java virtual machine.
  `static void`
  `halt(ExitUtil.HaltException he)`
  Halts the JVM if halt is enabled, rethrow provided exception or any raised error otherwise.
  `static boolean`
  `haltCalled()`
  `static void`
  `haltOnOutOfMemory(OutOfMemoryError oome)`
  Handler for out of memory events -no attempt is made here to cleanly shutdown or support halt blocking; a robust printing of the event to stderr is all that can be done.
  `static void`
  `resetFirstExitException()`
  Reset the tracking of process termination.
  `static void`
  `resetFirstHaltException()`
  Reset the tracking of process termination.
  `static void`
  `terminate(int status)`
  Like `terminate(int, Throwable)` without a message.
  `static void`
  `terminate(int status, String msg)`
  Terminate the current process.
  `static void`
  `terminate(int status, Throwable t)`
  Like `terminate(int, String)` but uses the given throwable to build the message to display or throw as an `ExitUtil.ExitException`.
  `static void`
  `terminate(ExitUtil.ExitException ee)`
  Exits the JVM if exit is enabled, rethrow provided exception or any raised error otherwise.
  `static boolean`
  `terminateCalled()`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### EXIT_EXCEPTION_MESSAGE

    public static final String EXIT_EXCEPTION_MESSAGE
    Message raised from an exit exception if none were provided: "ExitException".
    See Also:
      - Constant Field Values

  - ### HALT_EXCEPTION_MESSAGE

    public static final String HALT_EXCEPTION_MESSAGE
    Message raised from a halt exception if none were provided: "HaltException".
    See Also:
      - Constant Field Values

- ## Method Details

  - ### disableSystemExit

    public static void disableSystemExit()
    Disable the use of System.exit for testing.

  - ### enableSystemExit

    public static void enableSystemExit()
    Enable the use of System.exit for testing.

  - ### disableSystemHalt

    public static void disableSystemHalt()
    Disable the use of `Runtime.getRuntime().halt()` for testing.

  - ### terminateCalled

    public static boolean terminateCalled()
    Returns:
      true if terminate has been called.

  - ### haltCalled

    public static boolean haltCalled()
    Returns:
      true if halt has been called.

  - ### getFirstExitException

    public static ExitUtil.ExitException getFirstExitException()
    Returns:
      the first `ExitException` thrown, null if none thrown yet.

  - ### getFirstHaltException

    public static ExitUtil.HaltException getFirstHaltException()
    Returns:
      the first `HaltException` thrown, null if none thrown yet.

  - ### resetFirstExitException

    public static void resetFirstExitException()
    Reset the tracking of process termination. This is for use in unit tests where one test in the suite expects an exit but others do not.

  - ### resetFirstHaltException

    public static void resetFirstHaltException()
    Reset the tracking of process termination. This is for use in unit tests where one test in the suite expects a halt but others do not.

  - ### terminate

    public static void terminate(ExitUtil.ExitException ee) throws ExitUtil.ExitException
    Exits the JVM if exit is enabled, rethrow provided exception or any raised error otherwise. Inner termination: either exit with the exception's exit code, or, if system exits are disabled, rethrow the exception.
    Parameters:
      `ee` - exit exception
    Throws:
      `ExitUtil.ExitException` - if `System.exit(int)` is disabled and not suppressed by an Error
      `Error` - if `System.exit(int)` is disabled and one Error arise, suppressing anything else, even `ee`

  - ### halt

    public static void halt(ExitUtil.HaltException he) throws ExitUtil.HaltException
    Halts the JVM if halt is enabled, rethrow provided exception or any raised error otherwise. If halt is disabled, this method throws either the exception argument if no error arise, the first error if at least one arise, suppressing `he`. If halt is enabled, all throwables are caught, even errors.
    Parameters:
      `he` - the exception containing the status code, message and any stack trace.
    Throws:
      `ExitUtil.HaltException` - if `Runtime.halt(int)` is disabled and not suppressed by an Error
      `Error` - if `Runtime.halt(int)` is disabled and one Error arise, suppressing anyuthing else, even `he`

  - ### terminate

    public static void terminate(int status, Throwable t) throws ExitUtil.ExitException
    Like `terminate(int, String)` but uses the given throwable to build the message to display or throw as an `ExitUtil.ExitException`.

    Parameters:
      `status` - exit code to use if the exception is not an ExitException.
      `t` - throwable which triggered the termination. If this exception is an `ExitUtil.ExitException` its status overrides that passed in.
    Throws:
      `ExitUtil.ExitException` - if `System.exit(int)` is disabled.

  - ### halt

    public static void halt(int status, Throwable t) throws ExitUtil.HaltException
    Forcibly terminates the currently running Java virtual machine.
    Parameters:
      `status` - exit code to use if the exception is not a HaltException.
      `t` - throwable which triggered the termination. If this exception is a `ExitUtil.HaltException` its status overrides that passed in.
    Throws:
      `ExitUtil.HaltException` - if `System.exit(int)` is disabled.

  - ### terminate

    public static void terminate(int status) throws ExitUtil.ExitException
    Like `terminate(int, Throwable)` without a message.
    Parameters:
      `status` - exit code
    Throws:
      `ExitUtil.ExitException` - if `System.exit(int)` is disabled.

  - ### terminate

    public static void terminate(int status, String msg) throws ExitUtil.ExitException
    Terminate the current process. Note that terminate is the *only* method that should be used to terminate the daemon processes.
    Parameters:
      `status` - exit code
      `msg` - message used to create the `ExitException`
    Throws:
      `ExitUtil.ExitException` - if `System.exit(int)` is disabled.

  - ### halt

    public static void halt(int status) throws ExitUtil.HaltException
    Forcibly terminates the currently running Java virtual machine.
    Parameters:
      `status` - status code
    Throws:
      `ExitUtil.HaltException` - if `Runtime.halt(int)` is disabled.

  - ### halt

    public static void halt(int status, String message) throws ExitUtil.HaltException
    Forcibly terminates the currently running Java virtual machine.
    Parameters:
      `status` - status code
      `message` - message
    Throws:
      `ExitUtil.HaltException` - if `Runtime.halt(int)` is disabled.

  - ### haltOnOutOfMemory

    public static void haltOnOutOfMemory(OutOfMemoryError oome)
    Handler for out of memory events -no attempt is made here to cleanly shutdown or support halt blocking; a robust printing of the event to stderr is all that can be done.
    Parameters:
      `oome` - out of memory event