jdk/src/share/classes/sun/misc/Signal.java
author duke
Sat, 01 Dec 2007 00:00:00 +0000
changeset 2 90ce3da70b43
child 5506 202f599c92aa
permissions -rw-r--r--
Initial load
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     1
/*
90ce3da70b43 Initial load
duke
parents:
diff changeset
     2
 * Copyright 1998-2007 Sun Microsystems, Inc.  All Rights Reserved.
90ce3da70b43 Initial load
duke
parents:
diff changeset
     3
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
90ce3da70b43 Initial load
duke
parents:
diff changeset
     4
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
     5
 * This code is free software; you can redistribute it and/or modify it
90ce3da70b43 Initial load
duke
parents:
diff changeset
     6
 * under the terms of the GNU General Public License version 2 only, as
90ce3da70b43 Initial load
duke
parents:
diff changeset
     7
 * published by the Free Software Foundation.  Sun designates this
90ce3da70b43 Initial load
duke
parents:
diff changeset
     8
 * particular file as subject to the "Classpath" exception as provided
90ce3da70b43 Initial load
duke
parents:
diff changeset
     9
 * by Sun in the LICENSE file that accompanied this code.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    10
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    11
 * This code is distributed in the hope that it will be useful, but WITHOUT
90ce3da70b43 Initial load
duke
parents:
diff changeset
    12
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
90ce3da70b43 Initial load
duke
parents:
diff changeset
    13
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
90ce3da70b43 Initial load
duke
parents:
diff changeset
    14
 * version 2 for more details (a copy is included in the LICENSE file that
90ce3da70b43 Initial load
duke
parents:
diff changeset
    15
 * accompanied this code).
90ce3da70b43 Initial load
duke
parents:
diff changeset
    16
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    17
 * You should have received a copy of the GNU General Public License version
90ce3da70b43 Initial load
duke
parents:
diff changeset
    18
 * 2 along with this work; if not, write to the Free Software Foundation,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    19
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    20
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    21
 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    22
 * CA 95054 USA or visit www.sun.com if you need additional information or
90ce3da70b43 Initial load
duke
parents:
diff changeset
    23
 * have any questions.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    24
 */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    25
90ce3da70b43 Initial load
duke
parents:
diff changeset
    26
package sun.misc;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    27
import java.util.Hashtable;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    28
90ce3da70b43 Initial load
duke
parents:
diff changeset
    29
/**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    30
 * This class provides ANSI/ISO C signal support. A Java program can register
90ce3da70b43 Initial load
duke
parents:
diff changeset
    31
 * signal handlers for the current process. There are two restrictions:
90ce3da70b43 Initial load
duke
parents:
diff changeset
    32
 * <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    33
 * <li>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    34
 * Java code cannot register a handler for signals that are already used
90ce3da70b43 Initial load
duke
parents:
diff changeset
    35
 * by the Java VM implementation. The <code>Signal.handle</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    36
 * function raises an <code>IllegalArgumentException</code> if such an attempt
90ce3da70b43 Initial load
duke
parents:
diff changeset
    37
 * is made.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    38
 * <li>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    39
 * When <code>Signal.handle</code> is called, the VM internally registers a
90ce3da70b43 Initial load
duke
parents:
diff changeset
    40
 * special C signal handler. There is no way to force the Java signal handler
90ce3da70b43 Initial load
duke
parents:
diff changeset
    41
 * to run synchronously before the C signal handler returns. Instead, when the
90ce3da70b43 Initial load
duke
parents:
diff changeset
    42
 * VM receives a signal, the special C signal handler creates a new thread
90ce3da70b43 Initial load
duke
parents:
diff changeset
    43
 * (at priority <code>Thread.MAX_PRIORITY</code>) to
90ce3da70b43 Initial load
duke
parents:
diff changeset
    44
 * run the registered Java signal handler. The C signal handler immediately
90ce3da70b43 Initial load
duke
parents:
diff changeset
    45
 * returns. Note that because the Java signal handler runs in a newly created
90ce3da70b43 Initial load
duke
parents:
diff changeset
    46
 * thread, it may not actually be executed until some time after the C signal
90ce3da70b43 Initial load
duke
parents:
diff changeset
    47
 * handler returns.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    48
 * </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    49
 * <p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    50
 * Signal objects are created based on their names. For example:
90ce3da70b43 Initial load
duke
parents:
diff changeset
    51
 * <blockquote><pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    52
 * new Signal("INT");
90ce3da70b43 Initial load
duke
parents:
diff changeset
    53
 * </blockquote></pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    54
 * constructs a signal object corresponding to <code>SIGINT</code>, which is
90ce3da70b43 Initial load
duke
parents:
diff changeset
    55
 * typically produced when the user presses <code>Ctrl-C</code> at the command line.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    56
 * The <code>Signal</code> constructor throws <code>IllegalArgumentException</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    57
 * when it is passed an unknown signal.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    58
 * <p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    59
 * This is an example of how Java code handles <code>SIGINT</code>:
90ce3da70b43 Initial load
duke
parents:
diff changeset
    60
 * <blockquote><pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    61
 * SignalHandler handler = new SignalHandler () {
90ce3da70b43 Initial load
duke
parents:
diff changeset
    62
 *     public void handle(Signal sig) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
    63
 *       ... // handle SIGINT
90ce3da70b43 Initial load
duke
parents:
diff changeset
    64
 *     }
90ce3da70b43 Initial load
duke
parents:
diff changeset
    65
 * };
90ce3da70b43 Initial load
duke
parents:
diff changeset
    66
 * Signal.handle(new Signal("INT"), handler);
90ce3da70b43 Initial load
duke
parents:
diff changeset
    67
 * </blockquote></pre>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    68
 *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    69
 * @author   Sheng Liang
90ce3da70b43 Initial load
duke
parents:
diff changeset
    70
 * @author   Bill Shannon
90ce3da70b43 Initial load
duke
parents:
diff changeset
    71
 * @see      sun.misc.SignalHandler
90ce3da70b43 Initial load
duke
parents:
diff changeset
    72
 * @since    1.2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    73
 */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    74
public final class Signal {
90ce3da70b43 Initial load
duke
parents:
diff changeset
    75
    private static Hashtable handlers = new Hashtable(4);
90ce3da70b43 Initial load
duke
parents:
diff changeset
    76
    private static Hashtable signals = new Hashtable(4);
90ce3da70b43 Initial load
duke
parents:
diff changeset
    77
90ce3da70b43 Initial load
duke
parents:
diff changeset
    78
    private int number;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    79
    private String name;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    80
90ce3da70b43 Initial load
duke
parents:
diff changeset
    81
    /* Returns the signal number */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    82
    public int getNumber() {
90ce3da70b43 Initial load
duke
parents:
diff changeset
    83
        return number;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    84
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
    85
90ce3da70b43 Initial load
duke
parents:
diff changeset
    86
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    87
     * Returns the signal name.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    88
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    89
     * @return the name of the signal.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    90
     * @see sun.misc.Signal#Signal(String name)
90ce3da70b43 Initial load
duke
parents:
diff changeset
    91
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
    92
    public String getName() {
90ce3da70b43 Initial load
duke
parents:
diff changeset
    93
        return name;
90ce3da70b43 Initial load
duke
parents:
diff changeset
    94
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
    95
90ce3da70b43 Initial load
duke
parents:
diff changeset
    96
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
    97
     * Compares the equality of two <code>Signal</code> objects.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    98
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
    99
     * @param other the object to compare with.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   100
     * @return whether two <code>Signal</code> objects are equal.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   101
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   102
    public boolean equals(Object other) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   103
        if (this == other) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   104
            return true;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   105
        }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   106
        if (other == null || !(other instanceof Signal)) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   107
            return false;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   108
        }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   109
        Signal other1 = (Signal)other;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   110
        return name.equals(other1.name) && (number == other1.number);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   111
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   112
90ce3da70b43 Initial load
duke
parents:
diff changeset
   113
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   114
     * Returns a hashcode for this Signal.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   115
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   116
     * @return  a hash code value for this object.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   117
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   118
    public int hashCode() {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   119
        return number;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   120
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   121
90ce3da70b43 Initial load
duke
parents:
diff changeset
   122
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   123
     * Returns a string representation of this signal. For example, "SIGINT"
90ce3da70b43 Initial load
duke
parents:
diff changeset
   124
     * for an object constructed using <code>new Signal ("INT")</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   125
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   126
     * @return a string representation of the signal
90ce3da70b43 Initial load
duke
parents:
diff changeset
   127
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   128
    public String toString() {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   129
        return "SIG" + name;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   130
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   131
90ce3da70b43 Initial load
duke
parents:
diff changeset
   132
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   133
     * Constructs a signal from its name.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   134
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   135
     * @param name the name of the signal.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   136
     * @exception IllegalArgumentException unknown signal
90ce3da70b43 Initial load
duke
parents:
diff changeset
   137
     * @see sun.misc.Signal#getName()
90ce3da70b43 Initial load
duke
parents:
diff changeset
   138
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   139
    public Signal(String name) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   140
        number = findSignal(name);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   141
        this.name = name;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   142
        if (number < 0) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   143
            throw new IllegalArgumentException("Unknown signal: " + name);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   144
        }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   145
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   146
90ce3da70b43 Initial load
duke
parents:
diff changeset
   147
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   148
     * Registers a signal handler.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   149
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   150
     * @param sig a signal
90ce3da70b43 Initial load
duke
parents:
diff changeset
   151
     * @param handler the handler to be registered with the given signal.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   152
     * @result the old handler
90ce3da70b43 Initial load
duke
parents:
diff changeset
   153
     * @exception IllegalArgumentException the signal is in use by the VM
90ce3da70b43 Initial load
duke
parents:
diff changeset
   154
     * @see sun.misc.Signal#raise(Signal sig)
90ce3da70b43 Initial load
duke
parents:
diff changeset
   155
     * @see sun.misc.SignalHandler
90ce3da70b43 Initial load
duke
parents:
diff changeset
   156
     * @see sun.misc.SignalHandler#SIG_DFL
90ce3da70b43 Initial load
duke
parents:
diff changeset
   157
     * @see sun.misc.SignalHandler#SIG_IGN
90ce3da70b43 Initial load
duke
parents:
diff changeset
   158
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   159
    public static synchronized SignalHandler handle(Signal sig,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   160
                                                    SignalHandler handler)
90ce3da70b43 Initial load
duke
parents:
diff changeset
   161
        throws IllegalArgumentException {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   162
        long newH = (handler instanceof NativeSignalHandler) ?
90ce3da70b43 Initial load
duke
parents:
diff changeset
   163
                      ((NativeSignalHandler)handler).getHandler() : 2;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   164
        long oldH = handle0(sig.number, newH);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   165
        if (oldH == -1) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   166
            throw new IllegalArgumentException
90ce3da70b43 Initial load
duke
parents:
diff changeset
   167
                ("Signal already used by VM or OS: " + sig);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   168
        }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   169
        signals.put(new Integer(sig.number), sig);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   170
        synchronized (handlers) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   171
            SignalHandler oldHandler = (SignalHandler)handlers.get(sig);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   172
            handlers.remove(sig);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   173
            if (newH == 2) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   174
                handlers.put(sig, handler);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   175
            }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   176
            if (oldH == 0) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   177
                return SignalHandler.SIG_DFL;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   178
            } else if (oldH == 1) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   179
                return SignalHandler.SIG_IGN;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   180
            } else if (oldH == 2) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   181
                return oldHandler;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   182
            } else {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   183
                return new NativeSignalHandler(oldH);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   184
            }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   185
        }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   186
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   187
90ce3da70b43 Initial load
duke
parents:
diff changeset
   188
    /**
90ce3da70b43 Initial load
duke
parents:
diff changeset
   189
     * Raises a signal in the current process.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   190
     *
90ce3da70b43 Initial load
duke
parents:
diff changeset
   191
     * @param sig a signal
90ce3da70b43 Initial load
duke
parents:
diff changeset
   192
     * @see sun.misc.Signal#handle(Signal sig, SignalHandler handler)
90ce3da70b43 Initial load
duke
parents:
diff changeset
   193
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   194
    public static void raise(Signal sig) throws IllegalArgumentException {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   195
        if (handlers.get(sig) == null) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   196
            throw new IllegalArgumentException("Unhandled signal: " + sig);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   197
        }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   198
        raise0(sig.number);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   199
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   200
90ce3da70b43 Initial load
duke
parents:
diff changeset
   201
    /* Called by the VM to execute Java signal handlers. */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   202
    private static void dispatch(final int number) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   203
        final Signal sig = (Signal)signals.get(new Integer(number));
90ce3da70b43 Initial load
duke
parents:
diff changeset
   204
        final SignalHandler handler = (SignalHandler)handlers.get(sig);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   205
90ce3da70b43 Initial load
duke
parents:
diff changeset
   206
        Runnable runnable = new Runnable () {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   207
            public void run() {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   208
              // Don't bother to reset the priority. Signal handler will
90ce3da70b43 Initial load
duke
parents:
diff changeset
   209
              // run at maximum priority inherited from the VM signal
90ce3da70b43 Initial load
duke
parents:
diff changeset
   210
              // dispatch thread.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   211
              // Thread.currentThread().setPriority(Thread.NORM_PRIORITY);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   212
                handler.handle(sig);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   213
            }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   214
        };
90ce3da70b43 Initial load
duke
parents:
diff changeset
   215
        if (handler != null) {
90ce3da70b43 Initial load
duke
parents:
diff changeset
   216
            new Thread(runnable, sig + " handler").start();
90ce3da70b43 Initial load
duke
parents:
diff changeset
   217
        }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   218
    }
90ce3da70b43 Initial load
duke
parents:
diff changeset
   219
90ce3da70b43 Initial load
duke
parents:
diff changeset
   220
    /* Find the signal number, given a name. Returns -1 for unknown signals. */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   221
    private static native int findSignal(String sigName);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   222
    /* Registers a native signal handler, and returns the old handler.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   223
     * Handler values:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   224
     *   0     default handler
90ce3da70b43 Initial load
duke
parents:
diff changeset
   225
     *   1     ignore the signal
90ce3da70b43 Initial load
duke
parents:
diff changeset
   226
     *   2     call back to Signal.dispatch
90ce3da70b43 Initial load
duke
parents:
diff changeset
   227
     *   other arbitrary native signal handlers
90ce3da70b43 Initial load
duke
parents:
diff changeset
   228
     */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   229
    private static native long handle0(int sig, long nativeH);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   230
    /* Raise a given signal number */
90ce3da70b43 Initial load
duke
parents:
diff changeset
   231
    private static native void raise0(int sig);
90ce3da70b43 Initial load
duke
parents:
diff changeset
   232
}