Source for java.lang.Thread

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