OSDN Git Service

2007-02-15 Andrew Haley <aph@redhat.com>
[pf3gnuchains/gcc-fork.git] / libjava / java / lang / Thread.java
1 /* Thread -- an independent thread of executable code
2    Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006
3    Free Software Foundation
4
5 This file is part of GNU Classpath.
6
7 GNU Classpath is free software; you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation; either version 2, or (at your option)
10 any later version.
11
12 GNU Classpath is distributed in the hope that it will be useful, but
13 WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15 General Public License for more details.
16
17 You should have received a copy of the GNU General Public License
18 along with GNU Classpath; see the file COPYING.  If not, write to the
19 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
20 02110-1301 USA.
21
22 Linking this library statically or dynamically with other modules is
23 making a combined work based on this library.  Thus, the terms and
24 conditions of the GNU General Public License cover the whole
25 combination.
26
27 As a special exception, the copyright holders of this library give you
28 permission to link this library with independent modules to produce an
29 executable, regardless of the license terms of these independent
30 modules, and to copy and distribute the resulting executable under
31 terms of your choice, provided that you also meet, for each linked
32 independent module, the terms and conditions of the license of that
33 module.  An independent module is a module which is not derived from
34 or based on this library.  If you modify this library, you may extend
35 this exception to your version of the library, but you are not
36 obligated to do so.  If you do not wish to do so, delete this
37 exception statement from your version. */
38
39 package java.lang;
40
41 import gnu.classpath.VMStackWalker;
42 import gnu.gcj.RawData;
43 import gnu.gcj.RawDataManaged;
44 import gnu.java.util.WeakIdentityHashMap;
45
46 import java.lang.management.ManagementFactory;
47 import java.lang.management.ThreadInfo;
48 import java.lang.management.ThreadMXBean;
49
50 import java.util.HashMap;
51 import java.util.Map;
52
53 import java.lang.reflect.InvocationTargetException;
54 import java.lang.reflect.Method;
55
56 /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
57  * "The Java Language Specification", ISBN 0-201-63451-1
58  * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
59  * Status:  Believed complete to version 1.4, with caveats. We do not
60  *          implement the deprecated (and dangerous) stop, suspend, and resume
61  *          methods. Security implementation is not complete.
62  */
63
64 /**
65  * Thread represents a single thread of execution in the VM. When an
66  * application VM starts up, it creates a non-daemon Thread which calls the
67  * main() method of a particular class.  There may be other Threads running,
68  * such as the garbage collection thread.
69  *
70  * <p>Threads have names to identify them.  These names are not necessarily
71  * unique. Every Thread has a priority, as well, which tells the VM which
72  * Threads should get more running time. New threads inherit the priority
73  * and daemon status of the parent thread, by default.
74  *
75  * <p>There are two methods of creating a Thread: you may subclass Thread and
76  * implement the <code>run()</code> method, at which point you may start the
77  * Thread by calling its <code>start()</code> method, or you may implement
78  * <code>Runnable</code> in the class you want to use and then call new
79  * <code>Thread(your_obj).start()</code>.
80  *
81  * <p>The virtual machine runs until all non-daemon threads have died (either
82  * by returning from the run() method as invoked by start(), or by throwing
83  * an uncaught exception); or until <code>System.exit</code> is called with
84  * adequate permissions.
85  *
86  * <p>It is unclear at what point a Thread should be added to a ThreadGroup,
87  * and at what point it should be removed. Should it be inserted when it
88  * starts, or when it is created?  Should it be removed when it is suspended
89  * or interrupted?  The only thing that is clear is that the Thread should be
90  * removed when it is stopped.
91  *
92  * @author Tom Tromey
93  * @author John Keiser
94  * @author Eric Blake (ebb9@email.byu.edu)
95  * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
96  * @see Runnable
97  * @see Runtime#exit(int)
98  * @see #run()
99  * @see #start()
100  * @see ThreadLocal
101  * @since 1.0
102  * @status updated to 1.4
103  */
104 public class Thread implements Runnable
105 {
106   /** The minimum priority for a Thread. */
107   public static final int MIN_PRIORITY = 1;
108
109   /** The priority a Thread gets by default. */
110   public static final int NORM_PRIORITY = 5;
111
112   /** The maximum priority for a Thread. */
113   public static final int MAX_PRIORITY = 10;
114
115   /**
116    * The group this thread belongs to. This is set to null by
117    * ThreadGroup.removeThread when the thread dies.
118    */
119   ThreadGroup group;
120
121   /** The object to run(), null if this is the target. */
122   private Runnable runnable;
123
124   /** The thread name, non-null. */
125   String name;
126
127   /** Whether the thread is a daemon. */
128   private boolean daemon;
129
130   /** The thread priority, 1 to 10. */
131   private int priority;
132
133   boolean interrupt_flag;
134
135   /** A thread is either alive, dead, or being sent a signal; if it is
136       being sent a signal, it is also alive.  Thus, if you want to
137       know if a thread is alive, it is sufficient to test 
138       alive_status != THREAD_DEAD. */
139   private static final byte THREAD_DEAD = 0;
140   private static final byte THREAD_ALIVE = 1;
141   private static final byte THREAD_SIGNALED = 2;
142
143   private boolean startable_flag;
144
145   /** The context classloader for this Thread. */
146   private ClassLoader contextClassLoader;
147
148   /** This thread's ID.  */
149   private final long threadId;
150
151   /** The next thread ID to use.  */
152   private static long nextThreadId;
153
154   /** Used to generate the next thread ID to use.  */
155   private static long totalThreadsCreated;
156
157   /** The default exception handler.  */
158   private static UncaughtExceptionHandler defaultHandler;
159
160   /** Thread local storage. Package accessible for use by
161     * InheritableThreadLocal.
162     */
163   WeakIdentityHashMap locals;
164
165   /** The uncaught exception handler.  */
166   UncaughtExceptionHandler exceptionHandler;
167
168   /** This object is recorded while the thread is blocked to permit
169    * monitoring and diagnostic tools to identify the reasons that
170    * threads are blocked.
171    */
172   private Object parkBlocker;
173
174   /** Used by Unsafe.park and Unsafe.unpark.  Se Unsafe for a full
175       description.  */
176   static final byte THREAD_PARK_RUNNING = 0;
177   static final byte THREAD_PARK_PERMIT = 1;
178   static final byte THREAD_PARK_PARKED = 2;
179   static final byte THREAD_PARK_DEAD = 3;
180
181   /** The access control state for this thread.  Package accessible
182     * for use by java.security.VMAccessControlState's native method.
183     */
184   Object accessControlState = null;
185   
186   // This describes the top-most interpreter frame for this thread.
187   RawData interp_frame;
188   
189   // This describes the top most frame in the composite (interp + JNI) stack
190   RawData frame;
191
192   // Current state.
193   volatile int state;
194
195   // Our native data - points to an instance of struct natThread.
196   RawDataManaged data;
197
198   /**
199    * Allocates a new <code>Thread</code> object. This constructor has
200    * the same effect as <code>Thread(null, null,</code>
201    * <i>gname</i><code>)</code>, where <b><i>gname</i></b> is
202    * a newly generated name. Automatically generated names are of the
203    * form <code>"Thread-"+</code><i>n</i>, where <i>n</i> is an integer.
204    * <p>
205    * Threads created this way must have overridden their
206    * <code>run()</code> method to actually do anything.  An example
207    * illustrating this method being used follows:
208    * <p><blockquote><pre>
209    *     import java.lang.*;
210    *
211    *     class plain01 implements Runnable {
212    *         String name;
213    *         plain01() {
214    *             name = null;
215    *         }
216    *         plain01(String s) {
217    *             name = s;
218    *         }
219    *         public void run() {
220    *             if (name == null)
221    *                 System.out.println("A new thread created");
222    *             else
223    *                 System.out.println("A new thread with name " + name +
224    *                                    " created");
225    *         }
226    *     }
227    *     class threadtest01 {
228    *         public static void main(String args[] ) {
229    *             int failed = 0 ;
230    *
231    *             <b>Thread t1 = new Thread();</b>
232    *             if (t1 != null)
233    *                 System.out.println("new Thread() succeed");
234    *             else {
235    *                 System.out.println("new Thread() failed");
236    *                 failed++;
237    *             }
238    *         }
239    *     }
240    * </pre></blockquote>
241    *
242    * @see     java.lang.Thread#Thread(java.lang.ThreadGroup,
243    *          java.lang.Runnable, java.lang.String)
244    */
245   public Thread()
246   {
247     this(null, null, gen_name());
248   }
249
250   /**
251    * Allocates a new <code>Thread</code> object. This constructor has
252    * the same effect as <code>Thread(null, target,</code>
253    * <i>gname</i><code>)</code>, where <i>gname</i> is
254    * a newly generated name. Automatically generated names are of the
255    * form <code>"Thread-"+</code><i>n</i>, where <i>n</i> is an integer.
256    *
257    * @param target the object whose <code>run</code> method is called.
258    * @see java.lang.Thread#Thread(java.lang.ThreadGroup,
259    *                              java.lang.Runnable, java.lang.String)
260    */
261   public Thread(Runnable target)
262   {
263     this(null, target, gen_name());
264   }
265
266   /**
267    * Allocates a new <code>Thread</code> object. This constructor has
268    * the same effect as <code>Thread(null, null, name)</code>.
269    *
270    * @param   name   the name of the new thread.
271    * @see     java.lang.Thread#Thread(java.lang.ThreadGroup,
272    *          java.lang.Runnable, java.lang.String)
273    */
274   public Thread(String name)
275   {
276     this(null, null, name);
277   }
278
279   /**
280    * Allocates a new <code>Thread</code> object. This constructor has
281    * the same effect as <code>Thread(group, target,</code>
282    * <i>gname</i><code>)</code>, where <i>gname</i> is
283    * a newly generated name. Automatically generated names are of the
284    * form <code>"Thread-"+</code><i>n</i>, where <i>n</i> is an integer.
285    *
286    * @param group the group to put the Thread into
287    * @param target the Runnable object to execute
288    * @throws SecurityException if this thread cannot access <code>group</code>
289    * @throws IllegalThreadStateException if group is destroyed
290    * @see #Thread(ThreadGroup, Runnable, String)
291    */
292   public Thread(ThreadGroup group, Runnable target)
293   {
294     this(group, target, gen_name());
295   }
296
297   /**
298    * Allocates a new <code>Thread</code> object. This constructor has
299    * the same effect as <code>Thread(group, null, name)</code>
300    *
301    * @param group the group to put the Thread into
302    * @param name the name for the Thread
303    * @throws NullPointerException if name is null
304    * @throws SecurityException if this thread cannot access <code>group</code>
305    * @throws IllegalThreadStateException if group is destroyed
306    * @see #Thread(ThreadGroup, Runnable, String)
307    */
308   public Thread(ThreadGroup group, String name)
309   {
310     this(group, null, name);
311   }
312
313   /**
314    * Allocates a new <code>Thread</code> object. This constructor has
315    * the same effect as <code>Thread(null, target, name)</code>.
316    *
317    * @param target the Runnable object to execute
318    * @param name the name for the Thread
319    * @throws NullPointerException if name is null
320    * @see #Thread(ThreadGroup, Runnable, String)
321    */
322   public Thread(Runnable target, String name)
323   {
324     this(null, target, name);
325   }
326
327   /**
328    * Allocate a new Thread object, with the specified ThreadGroup and name, and
329    * using the specified Runnable object's <code>run()</code> method to
330    * execute.  If the Runnable object is null, <code>this</code> (which is
331    * a Runnable) is used instead.
332    *
333    * <p>If the ThreadGroup is null, the security manager is checked. If a
334    * manager exists and returns a non-null object for
335    * <code>getThreadGroup</code>, that group is used; otherwise the group
336    * of the creating thread is used. Note that the security manager calls
337    * <code>checkAccess</code> if the ThreadGroup is not null.
338    *
339    * <p>The new Thread will inherit its creator's priority and daemon status.
340    * These can be changed with <code>setPriority</code> and
341    * <code>setDaemon</code>.
342    *
343    * @param group the group to put the Thread into
344    * @param target the Runnable object to execute
345    * @param name the name for the Thread
346    * @throws NullPointerException if name is null
347    * @throws SecurityException if this thread cannot access <code>group</code>
348    * @throws IllegalThreadStateException if group is destroyed
349    * @see Runnable#run()
350    * @see #run()
351    * @see #setDaemon(boolean)
352    * @see #setPriority(int)
353    * @see SecurityManager#checkAccess(ThreadGroup)
354    * @see ThreadGroup#checkAccess()
355    */
356   public Thread(ThreadGroup group, Runnable target, String name)
357   {
358     this(currentThread(), group, target, name);
359   }
360
361   /**
362    * Allocate a new Thread object, as if by
363    * <code>Thread(group, null, name)</code>, and give it the specified stack
364    * size, in bytes. The stack size is <b>highly platform independent</b>,
365    * and the virtual machine is free to round up or down, or ignore it
366    * completely.  A higher value might let you go longer before a
367    * <code>StackOverflowError</code>, while a lower value might let you go
368    * longer before an <code>OutOfMemoryError</code>.  Or, it may do absolutely
369    * nothing! So be careful, and expect to need to tune this value if your
370    * virtual machine even supports it.
371    *
372    * @param group the group to put the Thread into
373    * @param target the Runnable object to execute
374    * @param name the name for the Thread
375    * @param size the stack size, in bytes; 0 to be ignored
376    * @throws NullPointerException if name is null
377    * @throws SecurityException if this thread cannot access <code>group</code>
378    * @throws IllegalThreadStateException if group is destroyed
379    * @since 1.4
380    */
381   public Thread(ThreadGroup group, Runnable target, String name, long size)
382   {
383     // Just ignore stackSize for now.
384     this(currentThread(), group, target, name);
385   }
386
387   private Thread (Thread current, ThreadGroup g, Runnable r, String n)
388   {
389     // Make sure the current thread may create a new thread.
390     checkAccess();
391     
392     // The Class Libraries book says ``threadName cannot be null''.  I
393     // take this to mean NullPointerException.
394     if (n == null)
395       throw new NullPointerException ();
396       
397     if (g == null)
398       {
399         // If CURRENT is null, then we are bootstrapping the first thread. 
400         // Use ThreadGroup.root, the main threadgroup.
401         if (current == null)
402           group = ThreadGroup.root;
403         else
404           group = current.getThreadGroup();
405       }
406     else
407       group = g;
408
409     data = null;
410     interrupt_flag = false;
411     startable_flag = true;
412
413     synchronized (Thread.class)
414       {
415         this.threadId = nextThreadId++;
416       }
417
418     if (current != null)
419       {
420         group.checkAccess();
421
422         daemon = current.isDaemon();
423         int gmax = group.getMaxPriority();
424         int pri = current.getPriority();
425         priority = (gmax < pri ? gmax : pri);
426         contextClassLoader = current.contextClassLoader;
427         InheritableThreadLocal.newChildThread(this);
428       }
429     else
430       {
431         daemon = false;
432         priority = NORM_PRIORITY;
433       }
434
435     name = n;
436     group.addThread(this);
437     runnable = r;
438
439     initialize_native ();
440   }
441
442   /**
443    * Get the number of active threads in the current Thread's ThreadGroup.
444    * This implementation calls
445    * <code>currentThread().getThreadGroup().activeCount()</code>.
446    *
447    * @return the number of active threads in the current ThreadGroup
448    * @see ThreadGroup#activeCount()
449    */
450   public static int activeCount()
451   {
452     return currentThread().group.activeCount();
453   }
454
455   /**
456    * Check whether the current Thread is allowed to modify this Thread. This
457    * passes the check on to <code>SecurityManager.checkAccess(this)</code>.
458    *
459    * @throws SecurityException if the current Thread cannot modify this Thread
460    * @see SecurityManager#checkAccess(Thread)
461    */
462   public final void checkAccess()
463   {
464     SecurityManager sm = System.getSecurityManager();
465     if (sm != null)
466       sm.checkAccess(this);
467   }
468
469   /**
470    * Count the number of stack frames in this Thread.  The Thread in question
471    * must be suspended when this occurs.
472    *
473    * @return the number of stack frames in this Thread
474    * @throws IllegalThreadStateException if this Thread is not suspended
475    * @deprecated pointless, since suspend is deprecated
476    */
477   public native int countStackFrames();
478
479   /**
480    * Get the currently executing Thread. In the situation that the
481    * currently running thread was created by native code and doesn't
482    * have an associated Thread object yet, a new Thread object is
483    * constructed and associated with the native thread.
484    *
485    * @return the currently executing Thread
486    */
487   public static native Thread currentThread();
488
489   /**
490    * Originally intended to destroy this thread, this method was never
491    * implemented by Sun, and is hence a no-op.
492    *
493    * @deprecated This method was originally intended to simply destroy
494    *             the thread without performing any form of cleanup operation.
495    *             However, it was never implemented.  It is now deprecated
496    *             for the same reason as <code>suspend()</code>,
497    *             <code>stop()</code> and <code>resume()</code>; namely,
498    *             it is prone to deadlocks.  If a thread is destroyed while
499    *             it still maintains a lock on a resource, then this resource
500    *             will remain locked and any attempts by other threads to
501    *             access the resource will result in a deadlock.  Thus, even
502    *             an implemented version of this method would be still be
503    *             deprecated, due to its unsafe nature.
504    * @throws NoSuchMethodError as this method was never implemented.
505    */
506   public void destroy()
507   {
508     throw new NoSuchMethodError();
509   }
510   
511   /**
512    * Print a stack trace of the current thread to stderr using the same
513    * format as Throwable's printStackTrace() method.
514    *
515    * @see Throwable#printStackTrace()
516    */
517   public static void dumpStack()
518   {
519     (new Exception("Stack trace")).printStackTrace();
520   }
521
522   /**
523    * Copy every active thread in the current Thread's ThreadGroup into the
524    * array. Extra threads are silently ignored. This implementation calls
525    * <code>getThreadGroup().enumerate(array)</code>, which may have a
526    * security check, <code>checkAccess(group)</code>.
527    *
528    * @param array the array to place the Threads into
529    * @return the number of Threads placed into the array
530    * @throws NullPointerException if array is null
531    * @throws SecurityException if you cannot access the ThreadGroup
532    * @see ThreadGroup#enumerate(Thread[])
533    * @see #activeCount()
534    * @see SecurityManager#checkAccess(ThreadGroup)
535    */
536   public static int enumerate(Thread[] array)
537   {
538     return currentThread().group.enumerate(array);
539   }
540   
541   /**
542    * Get this Thread's name.
543    *
544    * @return this Thread's name
545    */
546   public final String getName()
547   {
548     return name;
549   }
550
551   /**
552    * Get this Thread's priority.
553    *
554    * @return the Thread's priority
555    */
556   public final int getPriority()
557   {
558     return priority;
559   }
560
561   /**
562    * Get the ThreadGroup this Thread belongs to. If the thread has died, this
563    * returns null.
564    *
565    * @return this Thread's ThreadGroup
566    */
567   public final ThreadGroup getThreadGroup()
568   {
569     return group;
570   }
571
572   /**
573    * Checks whether the current thread holds the monitor on a given object.
574    * This allows you to do <code>assert Thread.holdsLock(obj)</code>.
575    *
576    * @param obj the object to test lock ownership on.
577    * @return true if the current thread is currently synchronized on obj
578    * @throws NullPointerException if obj is null
579    * @since 1.4
580    */
581   public static native boolean holdsLock(Object obj);
582
583   /**
584    * Interrupt this Thread. First, there is a security check,
585    * <code>checkAccess</code>. Then, depending on the current state of the
586    * thread, various actions take place:
587    *
588    * <p>If the thread is waiting because of {@link #wait()},
589    * {@link #sleep(long)}, or {@link #join()}, its <i>interrupt status</i>
590    * will be cleared, and an InterruptedException will be thrown. Notice that
591    * this case is only possible if an external thread called interrupt().
592    *
593    * <p>If the thread is blocked in an interruptible I/O operation, in
594    * {@link java.nio.channels.InterruptibleChannel}, the <i>interrupt
595    * status</i> will be set, and ClosedByInterruptException will be thrown.
596    *
597    * <p>If the thread is blocked on a {@link java.nio.channels.Selector}, the
598    * <i>interrupt status</i> will be set, and the selection will return, with
599    * a possible non-zero value, as though by the wakeup() method.
600    *
601    * <p>Otherwise, the interrupt status will be set.
602    *
603    * @throws SecurityException if you cannot modify this Thread
604    */
605   public native void interrupt();
606
607   /**
608    * Determine whether the current Thread has been interrupted, and clear
609    * the <i>interrupted status</i> in the process.
610    *
611    * @return whether the current Thread has been interrupted
612    * @see #isInterrupted()
613    */
614   public static boolean interrupted()
615   {
616     return currentThread().isInterrupted(true);
617   }
618
619   /**
620    * Determine whether the given Thread has been interrupted, but leave
621    * the <i>interrupted status</i> alone in the process.
622    *
623    * @return whether the Thread has been interrupted
624    * @see #interrupted()
625    */
626   public boolean isInterrupted()
627   {
628     return interrupt_flag;
629   }
630
631   /**
632    * Determine whether this Thread is alive. A thread which is alive has
633    * started and not yet died.
634    *
635    * @return whether this Thread is alive
636    */
637   public final native boolean isAlive();
638
639   /**
640    * Tell whether this is a daemon Thread or not.
641    *
642    * @return whether this is a daemon Thread or not
643    * @see #setDaemon(boolean)
644    */
645   public final boolean isDaemon()
646   {
647     return daemon;
648   }
649
650   /**
651    * Wait forever for the Thread in question to die.
652    *
653    * @throws InterruptedException if the Thread is interrupted; it's
654    *         <i>interrupted status</i> will be cleared
655    */
656   public final void join() throws InterruptedException
657   {
658     join(0, 0);
659   }
660
661   /**
662    * Wait the specified amount of time for the Thread in question to die.
663    *
664    * @param ms the number of milliseconds to wait, or 0 for forever
665    * @throws InterruptedException if the Thread is interrupted; it's
666    *         <i>interrupted status</i> will be cleared
667    */
668   public final void join(long ms) throws InterruptedException
669   {
670     join(ms, 0);
671   }
672
673   /**
674    * Wait the specified amount of time for the Thread in question to die.
675    *
676    * <p>Note that 1,000,000 nanoseconds == 1 millisecond, but most VMs do
677    * not offer that fine a grain of timing resolution. Besides, there is
678    * no guarantee that this thread can start up immediately when time expires,
679    * because some other thread may be active.  So don't expect real-time
680    * performance.
681    *
682    * @param ms the number of milliseconds to wait, or 0 for forever
683    * @param ns the number of extra nanoseconds to sleep (0-999999)
684    * @throws InterruptedException if the Thread is interrupted; it's
685    *         <i>interrupted status</i> will be cleared
686    * @throws IllegalArgumentException if ns is invalid
687    * @XXX A ThreadListener would be nice, to make this efficient.
688    */
689   public final native void join(long ms, int ns)
690     throws InterruptedException;
691
692   /**
693    * Resume this Thread.  If the thread is not suspended, this method does
694    * nothing. To mirror suspend(), there may be a security check:
695    * <code>checkAccess</code>.
696    *
697    * @throws SecurityException if you cannot resume the Thread
698    * @see #checkAccess()
699    * @see #suspend()
700    * @deprecated pointless, since suspend is deprecated
701    */
702   public final native void resume();
703
704   private final native void finish_();
705
706   /**
707    * Determine whether the given Thread has been interrupted, but leave
708    * the <i>interrupted status</i> alone in the process.
709    *
710    * @return whether the current Thread has been interrupted
711    * @see #interrupted()
712    */
713   private boolean isInterrupted(boolean clear_flag)
714   {
715     boolean r = interrupt_flag;
716     if (clear_flag && r)
717       {
718         // Only clear the flag if we saw it as set. Otherwise this could 
719         // potentially cause us to miss an interrupt in a race condition, 
720         // because this method is not synchronized.
721         interrupt_flag = false;
722       }
723     return r;
724   }
725   
726   /**
727    * The method of Thread that will be run if there is no Runnable object
728    * associated with the Thread. Thread's implementation does nothing at all.
729    *
730    * @see #start()
731    * @see #Thread(ThreadGroup, Runnable, String)
732    */
733   public void run()
734   {
735     if (runnable != null)
736       runnable.run();
737   }
738
739   /**
740    * Set the daemon status of this Thread.  If this is a daemon Thread, then
741    * the VM may exit even if it is still running.  This may only be called
742    * before the Thread starts running. There may be a security check,
743    * <code>checkAccess</code>.
744    *
745    * @param daemon whether this should be a daemon thread or not
746    * @throws SecurityException if you cannot modify this Thread
747    * @throws IllegalThreadStateException if the Thread is active
748    * @see #isDaemon()
749    * @see #checkAccess()
750    */
751   public final void setDaemon(boolean daemon)
752   {
753     if (!startable_flag)
754       throw new IllegalThreadStateException();
755     checkAccess();
756     this.daemon = daemon;
757   }
758
759   /**
760    * Returns the context classloader of this Thread. The context
761    * classloader can be used by code that want to load classes depending
762    * on the current thread. Normally classes are loaded depending on
763    * the classloader of the current class. There may be a security check
764    * for <code>RuntimePermission("getClassLoader")</code> if the caller's
765    * class loader is not null or an ancestor of this thread's context class
766    * loader.
767    *
768    * @return the context class loader
769    * @throws SecurityException when permission is denied
770    * @see #setContextClassLoader(ClassLoader)
771    * @since 1.2
772    */
773   public synchronized ClassLoader getContextClassLoader()
774   {
775     if (contextClassLoader == null)
776       contextClassLoader = ClassLoader.getSystemClassLoader();
777
778     // Check if we may get the classloader
779     SecurityManager sm = System.getSecurityManager();
780     if (contextClassLoader != null && sm != null)
781       {
782         // Get the calling classloader
783         ClassLoader cl = VMStackWalker.getCallingClassLoader();
784         if (cl != null && !cl.isAncestorOf(contextClassLoader))
785           sm.checkPermission(new RuntimePermission("getClassLoader"));
786       }
787     return contextClassLoader;
788   }
789
790   /**
791    * Sets the context classloader for this Thread. When not explicitly set,
792    * the context classloader for a thread is the same as the context
793    * classloader of the thread that created this thread. The first thread has
794    * as context classloader the system classloader. There may be a security
795    * check for <code>RuntimePermission("setContextClassLoader")</code>.
796    *
797    * @param classloader the new context class loader
798    * @throws SecurityException when permission is denied
799    * @see #getContextClassLoader()
800    * @since 1.2
801    */
802   public synchronized void setContextClassLoader(ClassLoader classloader)
803   {
804     SecurityManager sm = System.getSecurityManager();
805     if (sm != null)
806       sm.checkPermission(new RuntimePermission("setContextClassLoader"));
807     this.contextClassLoader = classloader;
808   }
809
810   /**
811    * Set this Thread's name.  There may be a security check,
812    * <code>checkAccess</code>.
813    *
814    * @param name the new name for this Thread
815    * @throws NullPointerException if name is null
816    * @throws SecurityException if you cannot modify this Thread
817    */
818   public final void setName(String name)
819   {
820     checkAccess();
821     // The Class Libraries book says ``threadName cannot be null''.  I
822     // take this to mean NullPointerException.
823     if (name == null)
824       throw new NullPointerException();
825     this.name = name;
826   }
827
828   /**
829    * Yield to another thread. The Thread will not lose any locks it holds
830    * during this time. There are no guarantees which thread will be
831    * next to run, and it could even be this one, but most VMs will choose
832    * the highest priority thread that has been waiting longest.
833    */
834   public static native void yield();
835
836   /**
837    * Suspend the current Thread's execution for the specified amount of
838    * time. The Thread will not lose any locks it has during this time. There
839    * are no guarantees which thread will be next to run, but most VMs will
840    * choose the highest priority thread that has been waiting longest.
841    *
842    * @param ms the number of milliseconds to sleep, or 0 for forever
843    * @throws InterruptedException if the Thread is (or was) interrupted;
844    *         it's <i>interrupted status</i> will be cleared
845    * @throws IllegalArgumentException if ms is negative
846    * @see #interrupt()
847    * @see #notify()
848    * @see #wait(long)
849    */
850   public static void sleep(long ms) throws InterruptedException
851   {
852     sleep(ms, 0);
853   }
854
855   /**
856    * Suspend the current Thread's execution for the specified amount of
857    * time. The Thread will not lose any locks it has during this time. There
858    * are no guarantees which thread will be next to run, but most VMs will
859    * choose the highest priority thread that has been waiting longest.
860    * <p>
861    * Note that 1,000,000 nanoseconds == 1 millisecond, but most VMs
862    * do not offer that fine a grain of timing resolution. When ms is
863    * zero and ns is non-zero the Thread will sleep for at least one
864    * milli second. There is no guarantee that this thread can start up
865    * immediately when time expires, because some other thread may be
866    * active.  So don't expect real-time performance.
867    *
868    * @param ms the number of milliseconds to sleep, or 0 for forever
869    * @param ns the number of extra nanoseconds to sleep (0-999999)
870    * @throws InterruptedException if the Thread is (or was) interrupted;
871    *         it's <i>interrupted status</i> will be cleared
872    * @throws IllegalArgumentException if ms or ns is negative
873    *         or ns is larger than 999999.
874    * @see #interrupt()
875    * @see #notify()
876    * @see #wait(long, int)
877    */
878   public static native void sleep(long timeout, int nanos)
879     throws InterruptedException;
880
881   /**
882    * Start this Thread, calling the run() method of the Runnable this Thread
883    * was created with, or else the run() method of the Thread itself. This
884    * is the only way to start a new thread; calling run by yourself will just
885    * stay in the same thread. The virtual machine will remove the thread from
886    * its thread group when the run() method completes.
887    *
888    * @throws IllegalThreadStateException if the thread has already started
889    * @see #run()
890    */
891   public native void start();
892
893   /**
894    * Cause this Thread to stop abnormally because of the throw of a ThreadDeath
895    * error. If you stop a Thread that has not yet started, it will stop
896    * immediately when it is actually started.
897    *
898    * <p>This is inherently unsafe, as it can interrupt synchronized blocks and
899    * leave data in bad states.  Hence, there is a security check:
900    * <code>checkAccess(this)</code>, plus another one if the current thread
901    * is not this: <code>RuntimePermission("stopThread")</code>. If you must
902    * catch a ThreadDeath, be sure to rethrow it after you have cleaned up.
903    * ThreadDeath is the only exception which does not print a stack trace when
904    * the thread dies.
905    *
906    * @throws SecurityException if you cannot stop the Thread
907    * @see #interrupt()
908    * @see #checkAccess()
909    * @see #start()
910    * @see ThreadDeath
911    * @see ThreadGroup#uncaughtException(Thread, Throwable)
912    * @see SecurityManager#checkAccess(Thread)
913    * @see SecurityManager#checkPermission(Permission)
914    * @deprecated unsafe operation, try not to use
915    */
916   public final void stop()
917   {
918     // Argument doesn't matter, because this is no longer
919     // supported.
920     stop(null);
921   }
922
923   /**
924    * Cause this Thread to stop abnormally and throw the specified exception.
925    * If you stop a Thread that has not yet started, the stop is ignored
926    * (contrary to what the JDK documentation says).
927    * <b>WARNING</b>This bypasses Java security, and can throw a checked
928    * exception which the call stack is unprepared to handle. Do not abuse
929    * this power.
930    *
931    * <p>This is inherently unsafe, as it can interrupt synchronized blocks and
932    * leave data in bad states.  Hence, there is a security check:
933    * <code>checkAccess(this)</code>, plus another one if the current thread
934    * is not this: <code>RuntimePermission("stopThread")</code>. If you must
935    * catch a ThreadDeath, be sure to rethrow it after you have cleaned up.
936    * ThreadDeath is the only exception which does not print a stack trace when
937    * the thread dies.
938    *
939    * @param t the Throwable to throw when the Thread dies
940    * @throws SecurityException if you cannot stop the Thread
941    * @throws NullPointerException in the calling thread, if t is null
942    * @see #interrupt()
943    * @see #checkAccess()
944    * @see #start()
945    * @see ThreadDeath
946    * @see ThreadGroup#uncaughtException(Thread, Throwable)
947    * @see SecurityManager#checkAccess(Thread)
948    * @see SecurityManager#checkPermission(Permission)
949    * @deprecated unsafe operation, try not to use
950    */
951   public final native void stop(Throwable t);
952
953   /**
954    * Suspend this Thread.  It will not come back, ever, unless it is resumed.
955    *
956    * <p>This is inherently unsafe, as the suspended thread still holds locks,
957    * and can potentially deadlock your program.  Hence, there is a security
958    * check: <code>checkAccess</code>.
959    *
960    * @throws SecurityException if you cannot suspend the Thread
961    * @see #checkAccess()
962    * @see #resume()
963    * @deprecated unsafe operation, try not to use
964    */
965   public final native void suspend();
966
967   /**
968    * Set this Thread's priority. There may be a security check,
969    * <code>checkAccess</code>, then the priority is set to the smaller of
970    * priority and the ThreadGroup maximum priority.
971    *
972    * @param priority the new priority for this Thread
973    * @throws IllegalArgumentException if priority exceeds MIN_PRIORITY or
974    *         MAX_PRIORITY
975    * @throws SecurityException if you cannot modify this Thread
976    * @see #getPriority()
977    * @see #checkAccess()
978    * @see ThreadGroup#getMaxPriority()
979    * @see #MIN_PRIORITY
980    * @see #MAX_PRIORITY
981    */
982   public final native void setPriority(int newPriority);
983
984   /**
985    * Returns a string representation of this thread, including the
986    * thread's name, priority, and thread group.
987    *
988    * @return a human-readable String representing this Thread
989    */
990   public String toString()
991   {
992     return ("Thread[" + name + "," + priority + ","
993             + (group == null ? "" : group.getName()) + "]");
994   }
995
996   private final native void initialize_native();
997
998   private final native static String gen_name();
999
1000   /**
1001    * Returns the map used by ThreadLocal to store the thread local values.
1002    */
1003   static Map getThreadLocals()
1004   {
1005     Thread thread = currentThread();
1006     Map locals = thread.locals;
1007     if (locals == null)
1008       {
1009         locals = thread.locals = new WeakIdentityHashMap();
1010       }
1011     return locals;
1012   }
1013
1014   /** 
1015    * Assigns the given <code>UncaughtExceptionHandler</code> to this
1016    * thread.  This will then be called if the thread terminates due
1017    * to an uncaught exception, pre-empting that of the
1018    * <code>ThreadGroup</code>.
1019    *
1020    * @param h the handler to use for this thread.
1021    * @throws SecurityException if the current thread can't modify this thread.
1022    * @since 1.5 
1023    */
1024   public void setUncaughtExceptionHandler(UncaughtExceptionHandler h)
1025   {
1026     SecurityManager sm = SecurityManager.current; // Be thread-safe.
1027     if (sm != null)
1028       sm.checkAccess(this);    
1029     exceptionHandler = h;
1030   }
1031
1032   /** 
1033    * <p>
1034    * Returns the handler used when this thread terminates due to an
1035    * uncaught exception.  The handler used is determined by the following:
1036    * </p>
1037    * <ul>
1038    * <li>If this thread has its own handler, this is returned.</li>
1039    * <li>If not, then the handler of the thread's <code>ThreadGroup</code>
1040    * object is returned.</li>
1041    * <li>If both are unavailable, then <code>null</code> is returned
1042    *     (which can only happen when the thread was terminated since
1043    *      then it won't have an associated thread group anymore).</li>
1044    * </ul>
1045    * 
1046    * @return the appropriate <code>UncaughtExceptionHandler</code> or
1047    *         <code>null</code> if one can't be obtained.
1048    * @since 1.5 
1049    */
1050   public UncaughtExceptionHandler getUncaughtExceptionHandler()
1051   {
1052     // FIXME: if thread is dead, should return null...
1053     return exceptionHandler != null ? exceptionHandler : group;
1054   }
1055
1056   /** 
1057    * <p>
1058    * Sets the default uncaught exception handler used when one isn't
1059    * provided by the thread or its associated <code>ThreadGroup</code>.
1060    * This exception handler is used when the thread itself does not
1061    * have an exception handler, and the thread's <code>ThreadGroup</code>
1062    * does not override this default mechanism with its own.  As the group
1063    * calls this handler by default, this exception handler should not defer
1064    * to that of the group, as it may lead to infinite recursion.
1065    * </p>
1066    * <p>
1067    * Uncaught exception handlers are used when a thread terminates due to
1068    * an uncaught exception.  Replacing this handler allows default code to
1069    * be put in place for all threads in order to handle this eventuality.
1070    * </p>
1071    *
1072    * @param h the new default uncaught exception handler to use.
1073    * @throws SecurityException if a security manager is present and
1074    *                           disallows the runtime permission
1075    *                           "setDefaultUncaughtExceptionHandler".
1076    * @since 1.5 
1077    */
1078   public static void 
1079     setDefaultUncaughtExceptionHandler(UncaughtExceptionHandler h)
1080   {
1081     SecurityManager sm = SecurityManager.current; // Be thread-safe.
1082     if (sm != null)
1083       sm.checkPermission(new RuntimePermission("setDefaultUncaughtExceptionHandler"));    
1084     defaultHandler = h;
1085   }
1086
1087   /** 
1088    * Returns the handler used by default when a thread terminates
1089    * unexpectedly due to an exception, or <code>null</code> if one doesn't
1090    * exist.
1091    *
1092    * @return the default uncaught exception handler.
1093    * @since 1.5 
1094    */
1095   public static UncaughtExceptionHandler getDefaultUncaughtExceptionHandler()
1096   {
1097     return defaultHandler;
1098   }
1099   
1100   /** 
1101    * Returns the unique identifier for this thread.  This ID is generated
1102    * on thread creation, and may be re-used on its death.
1103    *
1104    * @return a positive long number representing the thread's ID.
1105    * @since 1.5 
1106    */
1107   public long getId()
1108   {
1109     return threadId;
1110   }
1111
1112   /**
1113    * <p>
1114    * This interface is used to handle uncaught exceptions
1115    * which cause a <code>Thread</code> to terminate.  When
1116    * a thread, t, is about to terminate due to an uncaught
1117    * exception, the virtual machine looks for a class which
1118    * implements this interface, in order to supply it with
1119    * the dying thread and its uncaught exception.
1120    * </p>
1121    * <p>
1122    * The virtual machine makes two attempts to find an
1123    * appropriate handler for the uncaught exception, in
1124    * the following order:
1125    * </p>
1126    * <ol>
1127    * <li>
1128    * <code>t.getUncaughtExceptionHandler()</code> --
1129    * the dying thread is queried first for a handler
1130    * specific to that thread.
1131    * </li>
1132    * <li>
1133    * <code>t.getThreadGroup()</code> --
1134    * the thread group of the dying thread is used to
1135    * handle the exception.  If the thread group has
1136    * no special requirements for handling the exception,
1137    * it may simply forward it on to
1138    * <code>Thread.getDefaultUncaughtExceptionHandler()</code>,
1139    * the default handler, which is used as a last resort.
1140    * </li>
1141    * </ol>
1142    * <p>
1143    * The first handler found is the one used to handle
1144    * the uncaught exception.
1145    * </p>
1146    *
1147    * @author Tom Tromey <tromey@redhat.com>
1148    * @author Andrew John Hughes <gnu_andrew@member.fsf.org>
1149    * @since 1.5
1150    * @see Thread#getUncaughtExceptionHandler()
1151    * @see Thread#setUncaughtExceptionHandler(UncaughtExceptionHandler)
1152    * @see Thread#getDefaultUncaughtExceptionHandler()
1153    * @see
1154    * Thread#setDefaultUncaughtExceptionHandler(java.lang.Thread.UncaughtExceptionHandler)
1155    */
1156   public interface UncaughtExceptionHandler
1157   {
1158     /**
1159      * Invoked by the virtual machine with the dying thread
1160      * and the uncaught exception.  Any exceptions thrown
1161      * by this method are simply ignored by the virtual
1162      * machine.
1163      *
1164      * @param thr the dying thread.
1165      * @param exc the uncaught exception.
1166      */
1167     void uncaughtException(Thread thr, Throwable exc);
1168   }
1169
1170   /** 
1171    * <p>
1172    * Represents the current state of a thread, according to the VM rather
1173    * than the operating system.  It can be one of the following:
1174    * </p>
1175    * <ul>
1176    * <li>NEW -- The thread has just been created but is not yet running.</li>
1177    * <li>RUNNABLE -- The thread is currently running or can be scheduled
1178    * to run.</li>
1179    * <li>BLOCKED -- The thread is blocked waiting on an I/O operation
1180    * or to obtain a lock.</li>
1181    * <li>WAITING -- The thread is waiting indefinitely for another thread
1182    * to do something.</li>
1183    * <li>TIMED_WAITING -- The thread is waiting for a specific amount of time
1184    * for another thread to do something.</li>
1185    * <li>TERMINATED -- The thread has exited.</li>
1186    * </ul>
1187    *
1188    * @since 1.5 
1189    */
1190   public enum State
1191   {
1192     BLOCKED, NEW, RUNNABLE, TERMINATED, TIMED_WAITING, WAITING;
1193   }
1194
1195
1196   /**
1197    * Returns the current state of the thread.  This
1198    * is designed for monitoring thread behaviour, rather
1199    * than for synchronization control.
1200    *
1201    * @return the current thread state.
1202    */
1203   public native State getState();
1204
1205   /**
1206    * <p>
1207    * Returns a map of threads to stack traces for each
1208    * live thread.  The keys of the map are {@link Thread}
1209    * objects, which map to arrays of {@link StackTraceElement}s.
1210    * The results obtained from Calling this method are
1211    * equivalent to calling {@link getStackTrace()} on each
1212    * thread in succession.  Threads may be executing while
1213    * this takes place, and the results represent a snapshot
1214    * of the thread at the time its {@link getStackTrace()}
1215    * method is called.
1216    * </p>
1217    * <p>
1218    * The stack trace information contains the methods called
1219    * by the thread, with the most recent method forming the
1220    * first element in the array.  The array will be empty
1221    * if the virtual machine can not obtain information on the
1222    * thread. 
1223    * </p>
1224    * <p>
1225    * To execute this method, the current security manager
1226    * (if one exists) must allow both the
1227    * <code>"getStackTrace"</code> and
1228    * <code>"modifyThreadGroup"</code> {@link RuntimePermission}s.
1229    * </p>
1230    * 
1231    * @return a map of threads to arrays of {@link StackTraceElement}s.
1232    * @throws SecurityException if a security manager exists, and
1233    *                           prevents either or both the runtime
1234    *                           permissions specified above.
1235    * @since 1.5
1236    * @see #getStackTrace()
1237    */
1238   public static Map<Thread, StackTraceElement[]> getAllStackTraces()
1239   {
1240     ThreadGroup group = currentThread().group;
1241     while (group.getParent() != null)
1242       group = group.getParent();
1243     int arraySize = group.activeCount();
1244     Thread[] threadList = new Thread[arraySize];
1245     int filled = group.enumerate(threadList);
1246     while (filled == arraySize)
1247       {
1248         arraySize *= 2;
1249         threadList = new Thread[arraySize];
1250         filled = group.enumerate(threadList);
1251       }
1252     Map traces = new HashMap();
1253     for (int a = 0; a < filled; ++a)
1254       traces.put(threadList[a],
1255                  threadList[a].getStackTrace());
1256     return traces;
1257   }
1258
1259   /**
1260    * <p>
1261    * Returns an array of {@link StackTraceElement}s
1262    * representing the current stack trace of this thread.
1263    * The first element of the array is the most recent
1264    * method called, and represents the top of the stack.
1265    * The elements continue in this order, with the last
1266    * element representing the bottom of the stack.
1267    * </p>
1268    * <p>
1269    * A zero element array is returned for threads which
1270    * have not yet started (and thus have not yet executed
1271    * any methods) or for those which have terminated.
1272    * Where the virtual machine can not obtain a trace for
1273    * the thread, an empty array is also returned.  The
1274    * virtual machine may also omit some methods from the
1275    * trace in non-zero arrays.
1276    * </p>
1277    * <p>
1278    * To execute this method, the current security manager
1279    * (if one exists) must allow both the
1280    * <code>"getStackTrace"</code> and
1281    * <code>"modifyThreadGroup"</code> {@link RuntimePermission}s.
1282    * </p>
1283    *
1284    * @return a stack trace for this thread.
1285    * @throws SecurityException if a security manager exists, and
1286    *                           prevents the use of the
1287    *                           <code>"getStackTrace"</code>
1288    *                           permission.
1289    * @since 1.5
1290    * @see #getAllStackTraces()
1291    */
1292   public StackTraceElement[] getStackTrace()
1293   {
1294     SecurityManager sm = SecurityManager.current; // Be thread-safe.
1295     if (sm != null)
1296       sm.checkPermission(new RuntimePermission("getStackTrace"));
1297
1298     // Calling java.lang.management via reflection means that
1299     // javax.management be overridden in the endorsed directory.
1300
1301     // This is the equivalent code:
1302     //
1303     //     ThreadMXBean bean = ManagementFactory.getThreadMXBean();
1304     //     ThreadInfo info = bean.getThreadInfo(getId(), Integer.MAX_VALUE);
1305     //     return info.getStackTrace();
1306
1307     try
1308       {
1309         try
1310           {
1311             Object bean 
1312               = (Class.forName("java.lang.management.ManagementFactory")
1313                  .getDeclaredMethod("getThreadMXBean")
1314                  .invoke(null));
1315             Object info = bean.getClass()
1316               .getDeclaredMethod("getThreadInfo", long.class, int.class)
1317               .invoke(bean, new Long(getId()), new Integer(Integer.MAX_VALUE));
1318             Object trace = info.getClass()
1319               .getDeclaredMethod("getStackTrace").invoke(info);
1320             return (StackTraceElement[])trace;
1321           }
1322         catch (InvocationTargetException e)
1323           {
1324             throw (Exception)e.getTargetException();
1325           }
1326       }
1327     catch (UnsupportedOperationException e)
1328       {
1329         throw e;
1330       }
1331     catch (Exception e)
1332       {
1333         throw new UnsupportedOperationException(e);
1334       }
1335   }
1336 }