Docjar: A Java Source and Docuemnt Enginecom.*    java.*    javax.*    org.*    all    new    plug-in

Quick Search    Search Deep

Source code: java/lang/Thread.java


1   /* Thread -- an independent thread of executable code
2      Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004
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 java.util.Map;
42  import java.util.WeakHashMap;
43  
44  /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
45   * "The Java Language Specification", ISBN 0-201-63451-1
46   * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
47   * Status:  Believed complete to version 1.4, with caveats. We do not
48   *          implement the deprecated (and dangerous) stop, suspend, and resume
49   *          methods. Security implementation is not complete.
50   */
51  
52  /**
53   * Thread represents a single thread of execution in the VM. When an
54   * application VM starts up, it creates a non-daemon Thread which calls the
55   * main() method of a particular class.  There may be other Threads running,
56   * such as the garbage collection thread.
57   *
58   * <p>Threads have names to identify them.  These names are not necessarily
59   * unique. Every Thread has a priority, as well, which tells the VM which
60   * Threads should get more running time. New threads inherit the priority
61   * and daemon status of the parent thread, by default.
62   *
63   * <p>There are two methods of creating a Thread: you may subclass Thread and
64   * implement the <code>run()</code> method, at which point you may start the
65   * Thread by calling its <code>start()</code> method, or you may implement
66   * <code>Runnable</code> in the class you want to use and then call new
67   * <code>Thread(your_obj).start()</code>.
68   *
69   * <p>The virtual machine runs until all non-daemon threads have died (either
70   * by returning from the run() method as invoked by start(), or by throwing
71   * an uncaught exception); or until <code>System.exit</code> is called with
72   * adequate permissions.
73   *
74   * <p>It is unclear at what point a Thread should be added to a ThreadGroup,
75   * and at what point it should be removed. Should it be inserted when it
76   * starts, or when it is created?  Should it be removed when it is suspended
77   * or interrupted?  The only thing that is clear is that the Thread should be
78   * removed when it is stopped.
79   *
80   * @author Tom Tromey
81   * @author John Keiser
82   * @author Eric Blake (ebb9@email.byu.edu)
83   * @see Runnable
84   * @see Runtime#exit(int)
85   * @see #run()
86   * @see #start()
87   * @see ThreadLocal
88   * @since 1.0
89   * @status updated to 1.4
90   */
91  public class Thread implements Runnable
92  {
93    /** The minimum priority for a Thread. */
94    public static final int MIN_PRIORITY = 1;
95  
96    /** The priority a Thread gets by default. */
97    public static final int NORM_PRIORITY = 5;
98  
99    /** The maximum priority for a Thread. */
100   public static final int MAX_PRIORITY = 10;
101 
102   /** The underlying VM thread, only set when the thread is actually running.
103    */
104   volatile VMThread vmThread;
105 
106   /**
107    * The group this thread belongs to. This is set to null by
108    * ThreadGroup.removeThread when the thread dies.
109    */
110   volatile ThreadGroup group;
111 
112   /** The object to run(), null if this is the target. */
113   final Runnable runnable;
114 
115   /** The thread name, non-null. */
116   volatile String name;
117 
118   /** Whether the thread is a daemon. */
119   volatile boolean daemon;
120 
121   /** The thread priority, 1 to 10. */
122   volatile int priority;
123 
124   /** Native thread stack size. 0 = use default */
125   private long stacksize;
126 
127   /** Was the thread stopped before it was started? */
128   Throwable stillborn;
129 
130   /** The context classloader for this Thread. */
131   private ClassLoader contextClassLoader;
132 
133   /** The next thread number to use. */
134   private static int numAnonymousThreadsCreated;
135 
136   /** Thread local storage. Package accessible for use by
137     * InheritableThreadLocal.
138     */
139   WeakHashMap locals;
140 
141   /**
142    * Allocates a new <code>Thread</code> object. This constructor has
143    * the same effect as <code>Thread(null, null,</code>
144    * <i>gname</i><code>)</code>, where <b><i>gname</i></b> is
145    * a newly generated name. Automatically generated names are of the
146    * form <code>"Thread-"+</code><i>n</i>, where <i>n</i> is an integer.
147    * <p>
148    * Threads created this way must have overridden their
149    * <code>run()</code> method to actually do anything.  An example
150    * illustrating this method being used follows:
151    * <p><blockquote><pre>
152    *     import java.lang.*;
153    *
154    *     class plain01 implements Runnable {
155    *         String name;
156    *         plain01() {
157    *             name = null;
158    *         }
159    *         plain01(String s) {
160    *             name = s;
161    *         }
162    *         public void run() {
163    *             if (name == null)
164    *                 System.out.println("A new thread created");
165    *             else
166    *                 System.out.println("A new thread with name " + name +
167    *                                    " created");
168    *         }
169    *     }
170    *     class threadtest01 {
171    *         public static void main(String args[] ) {
172    *             int failed = 0 ;
173    *
174    *             <b>Thread t1 = new Thread();</b>
175    *             if (t1 != null)
176    *                 System.out.println("new Thread() succeed");
177    *             else {
178    *                 System.out.println("new Thread() failed");
179    *                 failed++;
180    *             }
181    *         }
182    *     }
183    * </pre></blockquote>
184    *
185    * @see     java.lang.Thread#Thread(java.lang.ThreadGroup,
186    *          java.lang.Runnable, java.lang.String)
187    */
188   public Thread()
189   {
190     this(null, (Runnable) null);
191   }
192 
193   /**
194    * Allocates a new <code>Thread</code> object. This constructor has
195    * the same effect as <code>Thread(null, target,</code>
196    * <i>gname</i><code>)</code>, where <i>gname</i> is
197    * a newly generated name. Automatically generated names are of the
198    * form <code>"Thread-"+</code><i>n</i>, where <i>n</i> is an integer.
199    *
200    * @param target the object whose <code>run</code> method is called.
201    * @see java.lang.Thread#Thread(java.lang.ThreadGroup,
202    *                              java.lang.Runnable, java.lang.String)
203    */
204   public Thread(Runnable target)
205   {
206     this(null, target);
207   }
208 
209   /**
210    * Allocates a new <code>Thread</code> object. This constructor has
211    * the same effect as <code>Thread(null, null, name)</code>.
212    *
213    * @param   name   the name of the new thread.
214    * @see     java.lang.Thread#Thread(java.lang.ThreadGroup,
215    *          java.lang.Runnable, java.lang.String)
216    */
217   public Thread(String name)
218   {
219     this(null, null, name, 0);
220   }
221 
222   /**
223    * Allocates a new <code>Thread</code> object. This constructor has
224    * the same effect as <code>Thread(group, target,</code>
225    * <i>gname</i><code>)</code>, where <i>gname</i> is
226    * a newly generated name. Automatically generated names are of the
227    * form <code>"Thread-"+</code><i>n</i>, where <i>n</i> is an integer.
228    *
229    * @param group the group to put the Thread into
230    * @param target the Runnable object to execute
231    * @throws SecurityException if this thread cannot access <code>group</code>
232    * @throws IllegalThreadStateException if group is destroyed
233    * @see #Thread(ThreadGroup, Runnable, String)
234    */
235   public Thread(ThreadGroup group, Runnable target)
236   {
237     this(group, target, "Thread-" + ++numAnonymousThreadsCreated, 0);
238   }
239 
240   /**
241    * Allocates a new <code>Thread</code> object. This constructor has
242    * the same effect as <code>Thread(group, null, name)</code>
243    *
244    * @param group the group to put the Thread into
245    * @param name the name for the Thread
246    * @throws NullPointerException if name is null
247    * @throws SecurityException if this thread cannot access <code>group</code>
248    * @throws IllegalThreadStateException if group is destroyed
249    * @see #Thread(ThreadGroup, Runnable, String)
250    */
251   public Thread(ThreadGroup group, String name)
252   {
253     this(group, null, name, 0);
254   }
255 
256   /**
257    * Allocates a new <code>Thread</code> object. This constructor has
258    * the same effect as <code>Thread(null, target, name)</code>.
259    *
260    * @param target the Runnable object to execute
261    * @param name the name for the Thread
262    * @throws NullPointerException if name is null
263    * @see #Thread(ThreadGroup, Runnable, String)
264    */
265   public Thread(Runnable target, String name)
266   {
267     this(null, target, name, 0);
268   }
269 
270   /**
271    * Allocate a new Thread object, with the specified ThreadGroup and name, and
272    * using the specified Runnable object's <code>run()</code> method to
273    * execute.  If the Runnable object is null, <code>this</code> (which is
274    * a Runnable) is used instead.
275    *
276    * <p>If the ThreadGroup is null, the security manager is checked. If a
277    * manager exists and returns a non-null object for
278    * <code>getThreadGroup</code>, that group is used; otherwise the group
279    * of the creating thread is used. Note that the security manager calls
280    * <code>checkAccess</code> if the ThreadGroup is not null.
281    *
282    * <p>The new Thread will inherit its creator's priority and daemon status.
283    * These can be changed with <code>setPriority</code> and
284    * <code>setDaemon</code>.
285    *
286    * @param group the group to put the Thread into
287    * @param target the Runnable object to execute
288    * @param name the name for the Thread
289    * @throws NullPointerException if name is null
290    * @throws SecurityException if this thread cannot access <code>group</code>
291    * @throws IllegalThreadStateException if group is destroyed
292    * @see Runnable#run()
293    * @see #run()
294    * @see #setDaemon(boolean)
295    * @see #setPriority(int)
296    * @see SecurityManager#checkAccess(ThreadGroup)
297    * @see ThreadGroup#checkAccess()
298    */
299   public Thread(ThreadGroup group, Runnable target, String name)
300   {
301     this(group, target, name, 0);
302   }
303 
304   /**
305    * Allocate a new Thread object, as if by
306    * <code>Thread(group, null, name)</code>, and give it the specified stack
307    * size, in bytes. The stack size is <b>highly platform independent</b>,
308    * and the virtual machine is free to round up or down, or ignore it
309    * completely.  A higher value might let you go longer before a
310    * <code>StackOverflowError</code>, while a lower value might let you go
311    * longer before an <code>OutOfMemoryError</code>.  Or, it may do absolutely
312    * nothing! So be careful, and expect to need to tune this value if your
313    * virtual machine even supports it.
314    *
315    * @param group the group to put the Thread into
316    * @param target the Runnable object to execute
317    * @param name the name for the Thread
318    * @param size the stack size, in bytes; 0 to be ignored
319    * @throws NullPointerException if name is null
320    * @throws SecurityException if this thread cannot access <code>group</code>
321    * @throws IllegalThreadStateException if group is destroyed
322    * @since 1.4
323    */
324   public Thread(ThreadGroup group, Runnable target, String name, long size)
325   {
326     // Bypass System.getSecurityManager, for bootstrap efficiency.
327     SecurityManager sm = SecurityManager.current;
328     Thread current = currentThread();
329     if (group == null)
330       {
331   if (sm != null)
332       group = sm.getThreadGroup();
333   if (group == null)
334       group = current.group;
335       }
336     else if (sm != null)
337   sm.checkAccess(group);
338 
339     this.group = group;
340     // Use toString hack to detect null.
341     this.name = name.toString();
342     this.runnable = target;
343     this.stacksize = size;
344 
345     priority = current.priority;
346     daemon = current.daemon;
347     contextClassLoader = current.contextClassLoader;
348 
349     group.addThread(this);
350     InheritableThreadLocal.newChildThread(this);
351   }
352 
353   /**
354    * Used by the VM to create thread objects for threads started outside
355    * of Java. Note: caller is responsible for adding the thread to
356    * a group and InheritableThreadLocal.
357    *
358    * @param vmThread the native thread
359    * @param name the thread name or null to use the default naming scheme
360    * @param priority current priority
361    * @param daemon is the thread a background thread?
362    */
363   Thread(VMThread vmThread, String name, int priority, boolean daemon)
364   {
365     this.vmThread = vmThread;
366     this.runnable = null;
367     if (name == null)
368   name = "Thread-" + ++numAnonymousThreadsCreated;
369     this.name = name;
370     this.priority = priority;
371     this.daemon = daemon;
372     this.contextClassLoader = ClassLoader.getSystemClassLoader();
373   }
374 
375   /**
376    * Get the number of active threads in the current Thread's ThreadGroup.
377    * This implementation calls
378    * <code>currentThread().getThreadGroup().activeCount()</code>.
379    *
380    * @return the number of active threads in the current ThreadGroup
381    * @see ThreadGroup#activeCount()
382    */
383   public static int activeCount()
384   {
385     return currentThread().group.activeCount();
386   }
387 
388   /**
389    * Check whether the current Thread is allowed to modify this Thread. This
390    * passes the check on to <code>SecurityManager.checkAccess(this)</code>.
391    *
392    * @throws SecurityException if the current Thread cannot modify this Thread
393    * @see SecurityManager#checkAccess(Thread)
394    */
395   public final void checkAccess()
396   {
397     // Bypass System.getSecurityManager, for bootstrap efficiency.
398     SecurityManager sm = SecurityManager.current;
399     if (sm != null)
400       sm.checkAccess(this);
401   }
402 
403   /**
404    * Count the number of stack frames in this Thread.  The Thread in question
405    * must be suspended when this occurs.
406    *
407    * @return the number of stack frames in this Thread
408    * @throws IllegalThreadStateException if this Thread is not suspended
409    * @deprecated pointless, since suspend is deprecated
410    */
411   public int countStackFrames()
412   {
413     VMThread t = vmThread;
414     if (t == null || group == null)
415   throw new IllegalThreadStateException();
416 
417     return t.countStackFrames();
418   }
419 
420   /**
421    * Get the currently executing Thread. In the situation that the
422    * currently running thread was created by native code and doesn't
423    * have an associated Thread object yet, a new Thread object is
424    * constructed and associated with the native thread.
425    *
426    * @return the currently executing Thread
427    */
428   public static Thread currentThread()
429   {
430     return VMThread.currentThread();
431   }
432 
433   /**
434    * Originally intended to destroy this thread, this method was never
435    * implemented by Sun, and is hence a no-op.
436    */
437   public void destroy()
438   {
439     throw new NoSuchMethodError();
440   }
441   
442   /**
443    * Print a stack trace of the current thread to stderr using the same
444    * format as Throwable's printStackTrace() method.
445    *
446    * @see Throwable#printStackTrace()
447    */
448   public static void dumpStack()
449   {
450     new Throwable().printStackTrace();
451   }
452 
453   /**
454    * Copy every active thread in the current Thread's ThreadGroup into the
455    * array. Extra threads are silently ignored. This implementation calls
456    * <code>getThreadGroup().enumerate(array)</code>, which may have a
457    * security check, <code>checkAccess(group)</code>.
458    *
459    * @param array the array to place the Threads into
460    * @return the number of Threads placed into the array
461    * @throws NullPointerException if array is null
462    * @throws SecurityException if you cannot access the ThreadGroup
463    * @see ThreadGroup#enumerate(Thread[])
464    * @see #activeCount()
465    * @see SecurityManager#checkAccess(ThreadGroup)
466    */
467   public static int enumerate(Thread[] array)
468   {
469     return currentThread().group.enumerate(array);
470   }
471   
472   /**
473    * Get this Thread's name.
474    *
475    * @return this Thread's name
476    */
477   public final String getName()
478   {
479     VMThread t = vmThread;
480     return t == null ? name : t.getName();
481   }
482 
483   /**
484    * Get this Thread's priority.
485    *
486    * @return the Thread's priority
487    */
488   public final synchronized int getPriority()
489   {
490     VMThread t = vmThread;
491     return t == null ? priority : t.getPriority();
492   }
493 
494   /**
495    * Get the ThreadGroup this Thread belongs to. If the thread has died, this
496    * returns null.
497    *
498    * @return this Thread's ThreadGroup
499    */
500   public final ThreadGroup getThreadGroup()
501   {
502     return group;
503   }
504 
505   /**
506    * Checks whether the current thread holds the monitor on a given object.
507    * This allows you to do <code>assert Thread.holdsLock(obj)</code>.
508    *
509    * @param obj the object to test lock ownership on.
510    * @return true if the current thread is currently synchronized on obj
511    * @throws NullPointerException if obj is null
512    * @since 1.4
513    */
514   public static boolean holdsLock(Object obj)
515   {
516     return VMThread.holdsLock(obj);
517   }
518 
519   /**
520    * Interrupt this Thread. First, there is a security check,
521    * <code>checkAccess</code>. Then, depending on the current state of the
522    * thread, various actions take place:
523    *
524    * <p>If the thread is waiting because of {@link #wait()},
525    * {@link #sleep(long)}, or {@link #join()}, its <i>interrupt status</i>
526    * will be cleared, and an InterruptedException will be thrown. Notice that
527    * this case is only possible if an external thread called interrupt().
528    *
529    * <p>If the thread is blocked in an interruptible I/O operation, in
530    * {@link java.nio.channels.InterruptibleChannel}, the <i>interrupt
531    * status</i> will be set, and ClosedByInterruptException will be thrown.
532    *
533    * <p>If the thread is blocked on a {@link java.nio.channels.Selector}, the
534    * <i>interrupt status</i> will be set, and the selection will return, with
535    * a possible non-zero value, as though by the wakeup() method.
536    *
537    * <p>Otherwise, the interrupt status will be set.
538    *
539    * @throws SecurityException if you cannot modify this Thread
540    */
541   public synchronized void interrupt()
542   {
543     checkAccess();
544     VMThread t = vmThread;
545     if (t != null)
546   t.interrupt();
547   }
548 
549   /**
550    * Determine whether the current Thread has been interrupted, and clear
551    * the <i>interrupted status</i> in the process.
552    *
553    * @return whether the current Thread has been interrupted
554    * @see #isInterrupted()
555    */
556   public static boolean interrupted()
557   {
558     return VMThread.interrupted();
559   }
560 
561   /**
562    * Determine whether the given Thread has been interrupted, but leave
563    * the <i>interrupted status</i> alone in the process.
564    *
565    * @return whether the Thread has been interrupted
566    * @see #interrupted()
567    */
568   public boolean isInterrupted()
569   {
570     VMThread t = vmThread;
571     return t != null && t.isInterrupted();
572   }
573 
574   /**
575    * Determine whether this Thread is alive. A thread which is alive has
576    * started and not yet died.
577    *
578    * @return whether this Thread is alive
579    */
580   public final boolean isAlive()
581   {
582     return vmThread != null && group != null;
583   }
584 
585   /**
586    * Tell whether this is a daemon Thread or not.
587    *
588    * @return whether this is a daemon Thread or not
589    * @see #setDaemon(boolean)
590    */
591   public final boolean isDaemon()
592   {
593     VMThread t = vmThread;
594     return t == null ? daemon : t.isDaemon();
595   }
596 
597   /**
598    * Wait forever for the Thread in question to die.
599    *
600    * @throws InterruptedException if the Thread is interrupted; it's
601    *         <i>interrupted status</i> will be cleared
602    */
603   public final void join() throws InterruptedException
604   {
605     join(0, 0);
606   }
607 
608   /**
609    * Wait the specified amount of time for the Thread in question to die.
610    *
611    * @param ms the number of milliseconds to wait, or 0 for forever
612    * @throws InterruptedException if the Thread is interrupted; it's
613    *         <i>interrupted status</i> will be cleared
614    */
615   public final void join(long ms) throws InterruptedException
616   {
617     join(ms, 0);
618   }
619 
620   /**
621    * Wait the specified amount of time for the Thread in question to die.
622    *
623    * <p>Note that 1,000,000 nanoseconds == 1 millisecond, but most VMs do
624    * not offer that fine a grain of timing resolution. Besides, there is
625    * no guarantee that this thread can start up immediately when time expires,
626    * because some other thread may be active.  So don't expect real-time
627    * performance.
628    *
629    * @param ms the number of milliseconds to wait, or 0 for forever
630    * @param ns the number of extra nanoseconds to sleep (0-999999)
631    * @throws InterruptedException if the Thread is interrupted; it's
632    *         <i>interrupted status</i> will be cleared
633    * @throws IllegalArgumentException if ns is invalid
634    */
635   public final void join(long ms, int ns) throws InterruptedException
636   {
637     if(ms < 0 || ns < 0 || ns > 999999)
638   throw new IllegalArgumentException();
639 
640     VMThread t = vmThread;
641     if(t != null)
642         t.join(ms, ns);
643   }
644 
645   /**
646    * Resume this Thread.  If the thread is not suspended, this method does
647    * nothing. To mirror suspend(), there may be a security check:
648    * <code>checkAccess</code>.
649    *
650    * @throws SecurityException if you cannot resume the Thread
651    * @see #checkAccess()
652    * @see #suspend()
653    * @deprecated pointless, since suspend is deprecated
654    */
655   public final synchronized void resume()
656   {
657     checkAccess();
658     VMThread t = vmThread;
659     if (t != null)
660   t.resume();
661   }
662   
663   /**
664    * The method of Thread that will be run if there is no Runnable object
665    * associated with the Thread. Thread's implementation does nothing at all.
666    *
667    * @see #start()
668    * @see #Thread(ThreadGroup, Runnable, String)
669    */
670   public void run()
671   {
672     if (runnable != null)
673       runnable.run();
674   }
675 
676   /**
677    * Set the daemon status of this Thread.  If this is a daemon Thread, then
678    * the VM may exit even if it is still running.  This may only be called
679    * before the Thread starts running. There may be a security check,
680    * <code>checkAccess</code>.
681    *
682    * @param daemon whether this should be a daemon thread or not
683    * @throws SecurityException if you cannot modify this Thread
684    * @throws IllegalThreadStateException if the Thread is active
685    * @see #isDaemon()
686    * @see #checkAccess()
687    */
688   public final synchronized void setDaemon(boolean daemon)
689   {
690     if (vmThread != null)
691       throw new IllegalThreadStateException();
692     checkAccess();
693     this.daemon = daemon;
694   }
695 
696   /**
697    * Returns the context classloader of this Thread. The context
698    * classloader can be used by code that want to load classes depending
699    * on the current thread. Normally classes are loaded depending on
700    * the classloader of the current class. There may be a security check
701    * for <code>RuntimePermission("getClassLoader")</code> if the caller's
702    * class loader is not null or an ancestor of this thread's context class
703    * loader.
704    *
705    * @return the context class loader
706    * @throws SecurityException when permission is denied
707    * @see setContextClassLoader(ClassLoader)
708    * @since 1.2
709    */
710   public synchronized ClassLoader getContextClassLoader()
711   {
712     // Bypass System.getSecurityManager, for bootstrap efficiency.
713     SecurityManager sm = SecurityManager.current;
714     if (sm != null)
715       // XXX Don't check this if the caller's class loader is an ancestor.
716       sm.checkPermission(new RuntimePermission("getClassLoader"));
717     return contextClassLoader;
718   }
719 
720   /**
721    * Sets the context classloader for this Thread. When not explicitly set,
722    * the context classloader for a thread is the same as the context
723    * classloader of the thread that created this thread. The first thread has
724    * as context classloader the system classloader. There may be a security
725    * check for <code>RuntimePermission("setContextClassLoader")</code>.
726    *
727    * @param classloader the new context class loader
728    * @throws SecurityException when permission is denied
729    * @see getContextClassLoader()
730    * @since 1.2
731    */
732   public synchronized void setContextClassLoader(ClassLoader classloader)
733   {
734     SecurityManager sm = SecurityManager.current;
735     if (sm != null)
736       sm.checkPermission(new RuntimePermission("setContextClassLoader"));
737     this.contextClassLoader = classloader;
738   }
739 
740   /**
741    * Set this Thread's name.  There may be a security check,
742    * <code>checkAccess</code>.
743    *
744    * @param name the new name for this Thread
745    * @throws NullPointerException if name is null
746    * @throws SecurityException if you cannot modify this Thread
747    */
748   public final synchronized void setName(String name)
749   {
750     checkAccess();
751     // The Class Libraries book says ``threadName cannot be null''.  I
752     // take this to mean NullPointerException.
753     if (name == null)
754       throw new NullPointerException();
755     VMThread t = vmThread;
756     if (t != null)
757   t.setName(name);
758     else
759   this.name = name;
760   }
761 
762   /**
763    * Yield to another thread. The Thread will not lose any locks it holds
764    * during this time. There are no guarantees which thread will be
765    * next to run, and it could even be this one, but most VMs will choose
766    * the highest priority thread that has been waiting longest.
767    */
768   public static void yield()
769   {
770     VMThread.yield();
771   }
772 
773   /**
774    * Suspend the current Thread's execution for the specified amount of
775    * time. The Thread will not lose any locks it has during this time. There
776    * are no guarantees which thread will be next to run, but most VMs will
777    * choose the highest priority thread that has been waiting longest.
778    *
779    * @param ms the number of milliseconds to sleep.
780    * @throws InterruptedException if the Thread is (or was) interrupted;
781    *         it's <i>interrupted status</i> will be cleared
782    * @throws IllegalArgumentException if ms is negative
783    * @see #interrupt()
784    */
785   public static void sleep(long ms) throws InterruptedException
786   {
787     sleep(ms, 0);
788   }
789 
790   /**
791    * Suspend the current Thread's execution for the specified amount of
792    * time. The Thread will not lose any locks it has during this time. There
793    * are no guarantees which thread will be next to run, but most VMs will
794    * choose the highest priority thread that has been waiting longest.
795    * <p>
796    * Note that 1,000,000 nanoseconds == 1 millisecond, but most VMs
797    * do not offer that fine a grain of timing resolution. When ms is
798    * zero and ns is non-zero the Thread will sleep for at least one
799    * milli second. There is no guarantee that this thread can start up
800    * immediately when time expires, because some other thread may be
801    * active.  So don't expect real-time performance.
802    *
803    * @param ms the number of milliseconds to sleep
804    * @param ns the number of extra nanoseconds to sleep (0-999999)
805    * @throws InterruptedException if the Thread is (or was) interrupted;
806    *         it's <i>interrupted status</i> will be cleared
807    * @throws IllegalArgumentException if ms or ns is negative
808    *         or ns is larger than 999999.
809    * @see #interrupt()
810    */
811   public static void sleep(long ms, int ns) throws InterruptedException
812   {
813 
814     // Check parameters
815     if (ms < 0 || ns < 0 || ns > 999999)
816       throw new IllegalArgumentException();
817 
818     // Really sleep
819     VMThread.sleep(ms, ns);
820   }
821 
822   /**
823    * Start this Thread, calling the run() method of the Runnable this Thread
824    * was created with, or else the run() method of the Thread itself. This
825    * is the only way to start a new thread; calling run by yourself will just
826    * stay in the same thread. The virtual machine will remove the thread from
827    * its thread group when the run() method completes.
828    *
829    * @throws IllegalThreadStateException if the thread has already started
830    * @see #run()
831    */
832   public synchronized void start()
833   {
834     if (vmThread != null || group == null)
835   throw new IllegalThreadStateException();
836 
837     VMThread.create(this, stacksize);
838   }
839   
840   /**
841    * Cause this Thread to stop abnormally because of the throw of a ThreadDeath
842    * error. If you stop a Thread that has not yet started, it will stop
843    * immediately when it is actually started.
844    *
845    * <p>This is inherently unsafe, as it can interrupt synchronized blocks and
846    * leave data in bad states.  Hence, there is a security check:
847    * <code>checkAccess(this)</code>, plus another one if the current thread
848    * is not this: <code>RuntimePermission("stopThread")</code>. If you must
849    * catch a ThreadDeath, be sure to rethrow it after you have cleaned up.
850    * ThreadDeath is the only exception which does not print a stack trace when
851    * the thread dies.
852    *
853    * @throws SecurityException if you cannot stop the Thread
854    * @see #interrupt()
855    * @see #checkAccess()
856    * @see #start()
857    * @see ThreadDeath
858    * @see ThreadGroup#uncaughtException(Thread, Throwable)
859    * @see SecurityManager#checkAccess(Thread)
860    * @see SecurityManager#checkPermission(Permission)
861    * @deprecated unsafe operation, try not to use
862    */
863   public final void stop()
864   {
865     stop(new ThreadDeath());
866   }
867 
868   /**
869    * Cause this Thread to stop abnormally and throw the specified exception.
870    * If you stop a Thread that has not yet started, the stop is ignored
871    * (contrary to what the JDK documentation says).
872    * <b>WARNING</b>This bypasses Java security, and can throw a checked
873    * exception which the call stack is unprepared to handle. Do not abuse
874    * this power.
875    *
876    * <p>This is inherently unsafe, as it can interrupt synchronized blocks and
877    * leave data in bad states.  Hence, there is a security check:
878    * <code>checkAccess(this)</code>, plus another one if the current thread
879    * is not this: <code>RuntimePermission("stopThread")</code>. If you must
880    * catch a ThreadDeath, be sure to rethrow it after you have cleaned up.
881    * ThreadDeath is the only exception which does not print a stack trace when
882    * the thread dies.
883    *
884    * @param t the Throwable to throw when the Thread dies
885    * @throws SecurityException if you cannot stop the Thread
886    * @throws NullPointerException in the calling thread, if t is null
887    * @see #interrupt()
888    * @see #checkAccess()
889    * @see #start()
890    * @see ThreadDeath
891    * @see ThreadGroup#uncaughtException(Thread, Throwable)
892    * @see SecurityManager#checkAccess(Thread)
893    * @see SecurityManager#checkPermission(Permission)
894    * @deprecated unsafe operation, try not to use
895    */
896   public final synchronized void stop(Throwable t)
897   {
898     if (t == null)
899       throw new NullPointerException();
900     // Bypass System.getSecurityManager, for bootstrap efficiency.
901     SecurityManager sm = SecurityManager.current;
902     if (sm != null)
903       {
904         sm.checkAccess(this);
905         if (this != currentThread())
906           sm.checkPermission(new RuntimePermission("stopThread"));
907       }
908     VMThread vt = vmThread;
909     if (vt != null)
910   vt.stop(t);
911     else
912   stillborn = t;
913   }
914 
915   /**
916    * Suspend this Thread.  It will not come back, ever, unless it is resumed.
917    *
918    * <p>This is inherently unsafe, as the suspended thread still holds locks,
919    * and can potentially deadlock your program.  Hence, there is a security
920    * check: <code>checkAccess</code>.
921    *
922    * @throws SecurityException if you cannot suspend the Thread
923    * @see #checkAccess()
924    * @see #resume()
925    * @deprecated unsafe operation, try not to use
926    */
927   public final synchronized void suspend()
928   {
929     checkAccess();
930     VMThread t = vmThread;
931     if (t != null)
932   t.suspend();
933   }
934 
935   /**
936    * Set this Thread's priority. There may be a security check,
937    * <code>checkAccess</code>, then the priority is set to the smaller of
938    * priority and the ThreadGroup maximum priority.
939    *
940    * @param priority the new priority for this Thread
941    * @throws IllegalArgumentException if priority exceeds MIN_PRIORITY or
942    *         MAX_PRIORITY
943    * @throws SecurityException if you cannot modify this Thread
944    * @see #getPriority()
945    * @see #checkAccess()
946    * @see ThreadGroup#getMaxPriority()
947    * @see #MIN_PRIORITY
948    * @see #MAX_PRIORITY
949    */
950   public final synchronized void setPriority(int priority)
951   {
952     checkAccess();
953     if (priority < MIN_PRIORITY || priority > MAX_PRIORITY)
954       throw new IllegalArgumentException("Invalid thread priority value "
955                                          + priority + ".");
956     priority = Math.min(priority, group.getMaxPriority());
957     VMThread t = vmThread;
958     if (t != null)
959   t.setPriority(priority);
960     else
961   this.priority = priority;
962   }
963 
964   /**
965    * Returns a string representation of this thread, including the
966    * thread's name, priority, and thread group.
967    *
968    * @return a human-readable String representing this Thread
969    */
970   public String toString()
971   {
972     return ("Thread[" + name + "," + priority + ","
973       + (group == null ? "" : group.getName()) + "]");
974   }
975 
976   /**
977    * Clean up code, called by VMThread when thread dies.
978    */
979   synchronized void die()
980   {
981     group.removeThread(this);
982     vmThread = null;
983     locals = null;
984   }
985 
986   /**
987    * Returns the map used by ThreadLocal to store the thread local values.
988    */
989   static Map getThreadLocals()
990   {
991     Thread thread = currentThread();
992     Map locals = thread.locals;
993     if (locals == null)
994       {
995         locals = thread.locals = new WeakHashMap();
996       }
997     return locals;
998   }
999 }