Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-4381444

Need to update documentation to reflect new semantics of -Xrs

    Details

    • Type: Bug
    • Status: Resolved
    • Priority: P2
    • Resolution: Fixed
    • Affects Version/s: 1.3.0, 1.3.1
    • Fix Version/s: 1.4.0
    • Component/s: docs
    • Labels:
      None
    • Subcomponent:
    • Resolved In Build:
      beta
    • CPU:
      generic, sparc
    • OS:
      generic, solaris_7

      Description

      Add documentation for the new semantics of option -Xrs
      (ReduceSignalUsage=true).

      See, for instance, bug # 4345157 for related details.


      Documentation along the following lines:

      In the non-standard options, document:

      -Xrs "Reduce usage of OS signals by Java/VM"

      [This also needs to be added to the java -X message).

      In the section that describes the signals used by the VM:

      (a) For Solaris add:

      "In J2SE 1.3, the Shutdown Hooks facility was introduced to allow orderly
      shutdown of a Java application. See <relevant section> for details of this
      feature. The Shutdown Hooks feature uses signals SIGHUP, SIGINT and SIGTERM
      to initiate shutdown sequences. When a native program that embeds the Java VM,
      or a native method, uses these signals (by replacing the default handlers
      for any of these signals), there is a possibility of interference with the
      Shutdown Hooks feature.

      "Similarly, the Java VM uses SIGQUIT to dump java thread stacks to allow
      monitoring or debugging of the Java application, a feature present also
      in J2SE 1.2 and earlier versions.

      "To avoid such interference, and to allow the user's native code to be able
      to control the handling of these signals, the `-Xrs' option may be used.
      This option turns off the the Shutdown Hooks feature, allowing the
      user's native code to install handlers for these signals without any
      interference with the virtual machine.

      "As an obvious side-effect, when the `-Xrs' option is used, neither the
      Shutdown Hooks feature nor the SIGQUIT thread dumping feature are available."

      (b) For Linux and Win32, appropriate modifications should be made to the
      above text to rename the signals to the ones used on these platforms.

      ----------------------------------------------------------------------
      Revised suggested text:
      ----
      Signal Usage by the Sun Java virtual machine, Shutdown Hooks, and
      Thread Dumping:

      In J2SE 1.3, the Shutdown Hooks facility was added to allow orderly
      shutdown of a Java application. The intent was to allow user cleanup
      code (such as closing database connections) to run at shutdown, even
      if the JVM terminates abruptly.

      On Unix platforms, Sun's JVM catches signals to implement shutdown
      hooks for abnormal VM termination; on Windows platforms, the JVM
      watches for console control events. Specifically, on Solaris and
      Linux, the JVM uses SIGHUP, SIGINT, and SIGTERM to initiate the
      running of shutdown hooks. On Windows, the VM registers a console
      control handler which begins shutdown hook processing and returns TRUE
      for CTRL_C_EVENT, CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT, and
      CTRL_SHUTDOWN_EVENT.

      The JVM uses a similar mechanism to implement the pre-1.2 feature of
      dumping thread stacks for debugging purposes. On Solaris and Linux,
      Sun's JVM uses SIGQUIT to perform thread dumps; on Windows,
      CTRL_BREAK_EVENT.

      On Unix platforms, applications embedding the VM frequently need to
      trap signals like SIGINT or SIGTERM. On Windows, if the JVM is run as
      a service (for example, the servlet engine for a web server), it can
      receive CTRL_LOGOFF_EVENT but should not initiate shutdown since the
      operating system will not actually terminate the process.

      To address these problems the -Xrs command line option has been added
      in 1.3.1. Specifying -Xrs to Sun's JVM has the following effects:

      1. On Solaris and Linux, the signal masks for SIGINT, SIGTERM, SIGHUP,
         and SIGQUIT are not changed by the JVM, and signal handlers for
         these signals are not installed.

      2. On Windows, the JVM does not install a console control handler,
         implying that it does not watch for or process CTRL_C_EVENT,
         CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT, or CTRL_SHUTDOWN_EVENT.

      The consequences of specifying -Xrs are twofold:

      1. SIGQUIT/Ctrl-Break thread dumps are not available.

      2. User code is responsible for causing shutdown hooks to run, for
         example by calling System.exit() when the JVM is to be terminated.


      kenneth.russell@eng 2000-11-22

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                asommere Alan Sommerer (Inactive)
                Reporter:
                ysr Y. Ramakrishna
              • Votes:
                0 Vote for this issue
                Watchers:
                2 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:
                  Imported:
                  Indexed: