Source for java.lang.Thread

   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, false);
 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, false);
 385:   }
 386: 
 387:   /**
 388:    * Allocate a new Thread object for threads used internally to the
 389:    * run time.  Runtime threads should not be members of an
 390:    * application ThreadGroup, nor should they execute arbitrary user
 391:    * code as part of the InheritableThreadLocal protocol.
 392:    *
 393:    * @param name the name for the Thread
 394:    * @param noInheritableThreadLocal if true, do not initialize
 395:    * InheritableThreadLocal variables for this thread.
 396:    * @throws IllegalThreadStateException if group is destroyed
 397:    */
 398:   Thread(String name, boolean noInheritableThreadLocal)
 399:   {
 400:     this(null, null, null, name, noInheritableThreadLocal);
 401:   }
 402:   
 403:   private Thread (Thread current, ThreadGroup g, Runnable r, String n, boolean noInheritableThreadLocal)
 404:   {
 405:     // Make sure the current thread may create a new thread.
 406:     checkAccess();
 407:     
 408:     // The Class Libraries book says ``threadName cannot be null''.  I
 409:     // take this to mean NullPointerException.
 410:     if (n == null)
 411:       throw new NullPointerException ();
 412:       
 413:     if (g == null)
 414:       {
 415:     // If CURRENT is null, then we are bootstrapping the first thread. 
 416:     // Use ThreadGroup.root, the main threadgroup.
 417:     if (current == null)
 418:       group = ThreadGroup.root;
 419:     else
 420:       group = current.getThreadGroup();
 421:       }
 422:     else
 423:       group = g;
 424: 
 425:     data = null;
 426:     interrupt_flag = false;
 427:     startable_flag = true;
 428: 
 429:     synchronized (Thread.class)
 430:       {
 431:         this.threadId = nextThreadId++;
 432:       }
 433: 
 434:     if (current != null)
 435:       {
 436:     group.checkAccess();
 437: 
 438:     daemon = current.isDaemon();
 439:         int gmax = group.getMaxPriority();
 440:     int pri = current.getPriority();
 441:     priority = (gmax < pri ? gmax : pri);
 442:     contextClassLoader = current.contextClassLoader;
 443:         // InheritableThreadLocal allows arbitrary user code to be
 444:         // executed, only do this if our caller desires it.
 445:         if (!noInheritableThreadLocal)
 446:           InheritableThreadLocal.newChildThread(this);
 447:       }
 448:     else
 449:       {
 450:     daemon = false;
 451:     priority = NORM_PRIORITY;
 452:       }
 453: 
 454:     name = n;
 455:     group.addThread(this);
 456:     runnable = r;
 457: 
 458:     initialize_native ();
 459:   }
 460: 
 461:   /**
 462:    * Get the number of active threads in the current Thread's ThreadGroup.
 463:    * This implementation calls
 464:    * <code>currentThread().getThreadGroup().activeCount()</code>.
 465:    *
 466:    * @return the number of active threads in the current ThreadGroup
 467:    * @see ThreadGroup#activeCount()
 468:    */
 469:   public static int activeCount()
 470:   {
 471:     return currentThread().group.activeCount();
 472:   }
 473: 
 474:   /**
 475:    * Check whether the current Thread is allowed to modify this Thread. This
 476:    * passes the check on to <code>SecurityManager.checkAccess(this)</code>.
 477:    *
 478:    * @throws SecurityException if the current Thread cannot modify this Thread
 479:    * @see SecurityManager#checkAccess(Thread)
 480:    */
 481:   public final void checkAccess()
 482:   {
 483:     SecurityManager sm = System.getSecurityManager();
 484:     if (sm != null)
 485:       sm.checkAccess(this);
 486:   }
 487: 
 488:   /**
 489:    * Count the number of stack frames in this Thread.  The Thread in question
 490:    * must be suspended when this occurs.
 491:    *
 492:    * @return the number of stack frames in this Thread
 493:    * @throws IllegalThreadStateException if this Thread is not suspended
 494:    * @deprecated pointless, since suspend is deprecated
 495:    */
 496:   public native int countStackFrames();
 497: 
 498:   /**
 499:    * Get the currently executing Thread. In the situation that the
 500:    * currently running thread was created by native code and doesn't
 501:    * have an associated Thread object yet, a new Thread object is
 502:    * constructed and associated with the native thread.
 503:    *
 504:    * @return the currently executing Thread
 505:    */
 506:   public static native Thread currentThread();
 507: 
 508:   /**
 509:    * Originally intended to destroy this thread, this method was never
 510:    * implemented by Sun, and is hence a no-op.
 511:    *
 512:    * @deprecated This method was originally intended to simply destroy
 513:    *             the thread without performing any form of cleanup operation.
 514:    *             However, it was never implemented.  It is now deprecated
 515:    *             for the same reason as <code>suspend()</code>,
 516:    *             <code>stop()</code> and <code>resume()</code>; namely,
 517:    *             it is prone to deadlocks.  If a thread is destroyed while
 518:    *             it still maintains a lock on a resource, then this resource
 519:    *             will remain locked and any attempts by other threads to
 520:    *             access the resource will result in a deadlock.  Thus, even
 521:    *             an implemented version of this method would be still be
 522:    *             deprecated, due to its unsafe nature.
 523:    * @throws NoSuchMethodError as this method was never implemented.
 524:    */
 525:   public void destroy()
 526:   {
 527:     throw new NoSuchMethodError();
 528:   }
 529:   
 530:   /**
 531:    * Print a stack trace of the current thread to stderr using the same
 532:    * format as Throwable's printStackTrace() method.
 533:    *
 534:    * @see Throwable#printStackTrace()
 535:    */
 536:   public static void dumpStack()
 537:   {
 538:     (new Exception("Stack trace")).printStackTrace();
 539:   }
 540: 
 541:   /**
 542:    * Copy every active thread in the current Thread's ThreadGroup into the
 543:    * array. Extra threads are silently ignored. This implementation calls
 544:    * <code>getThreadGroup().enumerate(array)</code>, which may have a
 545:    * security check, <code>checkAccess(group)</code>.
 546:    *
 547:    * @param array the array to place the Threads into
 548:    * @return the number of Threads placed into the array
 549:    * @throws NullPointerException if array is null
 550:    * @throws SecurityException if you cannot access the ThreadGroup
 551:    * @see ThreadGroup#enumerate(Thread[])
 552:    * @see #activeCount()
 553:    * @see SecurityManager#checkAccess(ThreadGroup)
 554:    */
 555:   public static int enumerate(Thread[] array)
 556:   {
 557:     return currentThread().group.enumerate(array);
 558:   }
 559:   
 560:   /**
 561:    * Get this Thread's name.
 562:    *
 563:    * @return this Thread's name
 564:    */
 565:   public final String getName()
 566:   {
 567:     return name;
 568:   }
 569: 
 570:   /**
 571:    * Get this Thread's priority.
 572:    *
 573:    * @return the Thread's priority
 574:    */
 575:   public final int getPriority()
 576:   {
 577:     return priority;
 578:   }
 579: 
 580:   /**
 581:    * Get the ThreadGroup this Thread belongs to. If the thread has died, this
 582:    * returns null.
 583:    *
 584:    * @return this Thread's ThreadGroup
 585:    */
 586:   public final ThreadGroup getThreadGroup()
 587:   {
 588:     return group;
 589:   }
 590: 
 591:   /**
 592:    * Checks whether the current thread holds the monitor on a given object.
 593:    * This allows you to do <code>assert Thread.holdsLock(obj)</code>.
 594:    *
 595:    * @param obj the object to test lock ownership on.
 596:    * @return true if the current thread is currently synchronized on obj
 597:    * @throws NullPointerException if obj is null
 598:    * @since 1.4
 599:    */
 600:   public static native boolean holdsLock(Object obj);
 601: 
 602:   /**
 603:    * Interrupt this Thread. First, there is a security check,
 604:    * <code>checkAccess</code>. Then, depending on the current state of the
 605:    * thread, various actions take place:
 606:    *
 607:    * <p>If the thread is waiting because of {@link #wait()},
 608:    * {@link #sleep(long)}, or {@link #join()}, its <i>interrupt status</i>
 609:    * will be cleared, and an InterruptedException will be thrown. Notice that
 610:    * this case is only possible if an external thread called interrupt().
 611:    *
 612:    * <p>If the thread is blocked in an interruptible I/O operation, in
 613:    * {@link java.nio.channels.InterruptibleChannel}, the <i>interrupt
 614:    * status</i> will be set, and ClosedByInterruptException will be thrown.
 615:    *
 616:    * <p>If the thread is blocked on a {@link java.nio.channels.Selector}, the
 617:    * <i>interrupt status</i> will be set, and the selection will return, with
 618:    * a possible non-zero value, as though by the wakeup() method.
 619:    *
 620:    * <p>Otherwise, the interrupt status will be set.
 621:    *
 622:    * @throws SecurityException if you cannot modify this Thread
 623:    */
 624:   public native void interrupt();
 625: 
 626:   /**
 627:    * Determine whether the current Thread has been interrupted, and clear
 628:    * the <i>interrupted status</i> in the process.
 629:    *
 630:    * @return whether the current Thread has been interrupted
 631:    * @see #isInterrupted()
 632:    */
 633:   public static boolean interrupted()
 634:   {
 635:     return currentThread().isInterrupted(true);
 636:   }
 637: 
 638:   /**
 639:    * Determine whether the given Thread has been interrupted, but leave
 640:    * the <i>interrupted status</i> alone in the process.
 641:    *
 642:    * @return whether the Thread has been interrupted
 643:    * @see #interrupted()
 644:    */
 645:   public boolean isInterrupted()
 646:   {
 647:     return interrupt_flag;
 648:   }
 649: 
 650:   /**
 651:    * Determine whether this Thread is alive. A thread which is alive has
 652:    * started and not yet died.
 653:    *
 654:    * @return whether this Thread is alive
 655:    */
 656:   public final native boolean isAlive();
 657: 
 658:   /**
 659:    * Tell whether this is a daemon Thread or not.
 660:    *
 661:    * @return whether this is a daemon Thread or not
 662:    * @see #setDaemon(boolean)
 663:    */
 664:   public final boolean isDaemon()
 665:   {
 666:     return daemon;
 667:   }
 668: 
 669:   /**
 670:    * Wait forever for the Thread in question to die.
 671:    *
 672:    * @throws InterruptedException if the Thread is interrupted; it's
 673:    *         <i>interrupted status</i> will be cleared
 674:    */
 675:   public final void join() throws InterruptedException
 676:   {
 677:     join(0, 0);
 678:   }
 679: 
 680:   /**
 681:    * Wait the specified amount of time for the Thread in question to die.
 682:    *
 683:    * @param ms the number of milliseconds to wait, or 0 for forever
 684:    * @throws InterruptedException if the Thread is interrupted; it's
 685:    *         <i>interrupted status</i> will be cleared
 686:    */
 687:   public final void join(long ms) throws InterruptedException
 688:   {
 689:     join(ms, 0);
 690:   }
 691: 
 692:   /**
 693:    * Wait the specified amount of time for the Thread in question to die.
 694:    *
 695:    * <p>Note that 1,000,000 nanoseconds == 1 millisecond, but most VMs do
 696:    * not offer that fine a grain of timing resolution. Besides, there is
 697:    * no guarantee that this thread can start up immediately when time expires,
 698:    * because some other thread may be active.  So don't expect real-time
 699:    * performance.
 700:    *
 701:    * @param ms the number of milliseconds to wait, or 0 for forever
 702:    * @param ns the number of extra nanoseconds to sleep (0-999999)
 703:    * @throws InterruptedException if the Thread is interrupted; it's
 704:    *         <i>interrupted status</i> will be cleared
 705:    * @throws IllegalArgumentException if ns is invalid
 706:    * @XXX A ThreadListener would be nice, to make this efficient.
 707:    */
 708:   public final native void join(long ms, int ns)
 709:     throws InterruptedException;
 710: 
 711:   /**
 712:    * Resume this Thread.  If the thread is not suspended, this method does
 713:    * nothing. To mirror suspend(), there may be a security check:
 714:    * <code>checkAccess</code>.
 715:    *
 716:    * @throws SecurityException if you cannot resume the Thread
 717:    * @see #checkAccess()
 718:    * @see #suspend()
 719:    * @deprecated pointless, since suspend is deprecated
 720:    */
 721:   public final native void resume();
 722: 
 723:   private final native void finish_();
 724: 
 725:   /**
 726:    * Determine whether the given Thread has been interrupted, but leave
 727:    * the <i>interrupted status</i> alone in the process.
 728:    *
 729:    * @return whether the current Thread has been interrupted
 730:    * @see #interrupted()
 731:    */
 732:   private boolean isInterrupted(boolean clear_flag)
 733:   {
 734:     boolean r = interrupt_flag;
 735:     if (clear_flag && r)
 736:       {
 737:     // Only clear the flag if we saw it as set. Otherwise this could 
 738:     // potentially cause us to miss an interrupt in a race condition, 
 739:     // because this method is not synchronized.
 740:     interrupt_flag = false;
 741:       }
 742:     return r;
 743:   }
 744:   
 745:   /**
 746:    * The method of Thread that will be run if there is no Runnable object
 747:    * associated with the Thread. Thread's implementation does nothing at all.
 748:    *
 749:    * @see #start()
 750:    * @see #Thread(ThreadGroup, Runnable, String)
 751:    */
 752:   public void run()
 753:   {
 754:     if (runnable != null)
 755:       runnable.run();
 756:   }
 757: 
 758:   /**
 759:    * Set the daemon status of this Thread.  If this is a daemon Thread, then
 760:    * the VM may exit even if it is still running.  This may only be called
 761:    * before the Thread starts running. There may be a security check,
 762:    * <code>checkAccess</code>.
 763:    *
 764:    * @param daemon whether this should be a daemon thread or not
 765:    * @throws SecurityException if you cannot modify this Thread
 766:    * @throws IllegalThreadStateException if the Thread is active
 767:    * @see #isDaemon()
 768:    * @see #checkAccess()
 769:    */
 770:   public final void setDaemon(boolean daemon)
 771:   {
 772:     if (!startable_flag)
 773:       throw new IllegalThreadStateException();
 774:     checkAccess();
 775:     this.daemon = daemon;
 776:   }
 777: 
 778:   /**
 779:    * Returns the context classloader of this Thread. The context
 780:    * classloader can be used by code that want to load classes depending
 781:    * on the current thread. Normally classes are loaded depending on
 782:    * the classloader of the current class. There may be a security check
 783:    * for <code>RuntimePermission("getClassLoader")</code> if the caller's
 784:    * class loader is not null or an ancestor of this thread's context class
 785:    * loader.
 786:    *
 787:    * @return the context class loader
 788:    * @throws SecurityException when permission is denied
 789:    * @see #setContextClassLoader(ClassLoader)
 790:    * @since 1.2
 791:    */
 792:   public synchronized ClassLoader getContextClassLoader()
 793:   {
 794:     if (contextClassLoader == null)
 795:       contextClassLoader = ClassLoader.getSystemClassLoader();
 796: 
 797:     // Check if we may get the classloader
 798:     SecurityManager sm = System.getSecurityManager();
 799:     if (contextClassLoader != null && sm != null)
 800:       {
 801:         // Get the calling classloader
 802:     ClassLoader cl = VMStackWalker.getCallingClassLoader();
 803:         if (cl != null && !cl.isAncestorOf(contextClassLoader))
 804:           sm.checkPermission(new RuntimePermission("getClassLoader"));
 805:       }
 806:     return contextClassLoader;
 807:   }
 808: 
 809:   /**
 810:    * Sets the context classloader for this Thread. When not explicitly set,
 811:    * the context classloader for a thread is the same as the context
 812:    * classloader of the thread that created this thread. The first thread has
 813:    * as context classloader the system classloader. There may be a security
 814:    * check for <code>RuntimePermission("setContextClassLoader")</code>.
 815:    *
 816:    * @param classloader the new context class loader
 817:    * @throws SecurityException when permission is denied
 818:    * @see #getContextClassLoader()
 819:    * @since 1.2
 820:    */
 821:   public synchronized void setContextClassLoader(ClassLoader classloader)
 822:   {
 823:     SecurityManager sm = System.getSecurityManager();
 824:     if (sm != null)
 825:       sm.checkPermission(new RuntimePermission("setContextClassLoader"));
 826:     this.contextClassLoader = classloader;
 827:   }
 828: 
 829:   /**
 830:    * Set this Thread's name.  There may be a security check,
 831:    * <code>checkAccess</code>.
 832:    *
 833:    * @param name the new name for this Thread
 834:    * @throws NullPointerException if name is null
 835:    * @throws SecurityException if you cannot modify this Thread
 836:    */
 837:   public final void setName(String name)
 838:   {
 839:     checkAccess();
 840:     // The Class Libraries book says ``threadName cannot be null''.  I
 841:     // take this to mean NullPointerException.
 842:     if (name == null)
 843:       throw new NullPointerException();
 844:     this.name = name;
 845:   }
 846: 
 847:   /**
 848:    * Yield to another thread. The Thread will not lose any locks it holds
 849:    * during this time. There are no guarantees which thread will be
 850:    * next to run, and it could even be this one, but most VMs will choose
 851:    * the highest priority thread that has been waiting longest.
 852:    */
 853:   public static native void yield();
 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:    *
 861:    * @param ms the number of milliseconds to sleep, or 0 for forever
 862:    * @throws InterruptedException if the Thread is (or was) interrupted;
 863:    *         it's <i>interrupted status</i> will be cleared
 864:    * @throws IllegalArgumentException if ms is negative
 865:    * @see #interrupt()
 866:    * @see #notify()
 867:    * @see #wait(long)
 868:    */
 869:   public static void sleep(long ms) throws InterruptedException
 870:   {
 871:     sleep(ms, 0);
 872:   }
 873: 
 874:   /**
 875:    * Suspend the current Thread's execution for the specified amount of
 876:    * time. The Thread will not lose any locks it has during this time. There
 877:    * are no guarantees which thread will be next to run, but most VMs will
 878:    * choose the highest priority thread that has been waiting longest.
 879:    * <p>
 880:    * Note that 1,000,000 nanoseconds == 1 millisecond, but most VMs
 881:    * do not offer that fine a grain of timing resolution. When ms is
 882:    * zero and ns is non-zero the Thread will sleep for at least one
 883:    * milli second. There is no guarantee that this thread can start up
 884:    * immediately when time expires, because some other thread may be
 885:    * active.  So don't expect real-time performance.
 886:    *
 887:    * @param ms the number of milliseconds to sleep, or 0 for forever
 888:    * @param ns the number of extra nanoseconds to sleep (0-999999)
 889:    * @throws InterruptedException if the Thread is (or was) interrupted;
 890:    *         it's <i>interrupted status</i> will be cleared
 891:    * @throws IllegalArgumentException if ms or ns is negative
 892:    *         or ns is larger than 999999.
 893:    * @see #interrupt()
 894:    * @see #notify()
 895:    * @see #wait(long, int)
 896:    */
 897:   public static native void sleep(long timeout, int nanos)
 898:     throws InterruptedException;
 899: 
 900:   /**
 901:    * Start this Thread, calling the run() method of the Runnable this Thread
 902:    * was created with, or else the run() method of the Thread itself. This
 903:    * is the only way to start a new thread; calling run by yourself will just
 904:    * stay in the same thread. The virtual machine will remove the thread from
 905:    * its thread group when the run() method completes.
 906:    *
 907:    * @throws IllegalThreadStateException if the thread has already started
 908:    * @see #run()
 909:    */
 910:   public native void start();
 911: 
 912:   /**
 913:    * Cause this Thread to stop abnormally because of the throw of a ThreadDeath
 914:    * error. If you stop a Thread that has not yet started, it will stop
 915:    * immediately when it is actually started.
 916:    *
 917:    * <p>This is inherently unsafe, as it can interrupt synchronized blocks and
 918:    * leave data in bad states.  Hence, there is a security check:
 919:    * <code>checkAccess(this)</code>, plus another one if the current thread
 920:    * is not this: <code>RuntimePermission("stopThread")</code>. If you must
 921:    * catch a ThreadDeath, be sure to rethrow it after you have cleaned up.
 922:    * ThreadDeath is the only exception which does not print a stack trace when
 923:    * the thread dies.
 924:    *
 925:    * @throws SecurityException if you cannot stop the Thread
 926:    * @see #interrupt()
 927:    * @see #checkAccess()
 928:    * @see #start()
 929:    * @see ThreadDeath
 930:    * @see ThreadGroup#uncaughtException(Thread, Throwable)
 931:    * @see SecurityManager#checkAccess(Thread)
 932:    * @see SecurityManager#checkPermission(Permission)
 933:    * @deprecated unsafe operation, try not to use
 934:    */
 935:   public final void stop()
 936:   {
 937:     // Argument doesn't matter, because this is no longer
 938:     // supported.
 939:     stop(null);
 940:   }
 941: 
 942:   /**
 943:    * Cause this Thread to stop abnormally and throw the specified exception.
 944:    * If you stop a Thread that has not yet started, the stop is ignored
 945:    * (contrary to what the JDK documentation says).
 946:    * <b>WARNING</b>This bypasses Java security, and can throw a checked
 947:    * exception which the call stack is unprepared to handle. Do not abuse
 948:    * this power.
 949:    *
 950:    * <p>This is inherently unsafe, as it can interrupt synchronized blocks and
 951:    * leave data in bad states.  Hence, there is a security check:
 952:    * <code>checkAccess(this)</code>, plus another one if the current thread
 953:    * is not this: <code>RuntimePermission("stopThread")</code>. If you must
 954:    * catch a ThreadDeath, be sure to rethrow it after you have cleaned up.
 955:    * ThreadDeath is the only exception which does not print a stack trace when
 956:    * the thread dies.
 957:    *
 958:    * @param t the Throwable to throw when the Thread dies
 959:    * @throws SecurityException if you cannot stop the Thread
 960:    * @throws NullPointerException in the calling thread, if t is null
 961:    * @see #interrupt()
 962:    * @see #checkAccess()
 963:    * @see #start()
 964:    * @see ThreadDeath
 965:    * @see ThreadGroup#uncaughtException(Thread, Throwable)
 966:    * @see SecurityManager#checkAccess(Thread)
 967:    * @see SecurityManager#checkPermission(Permission)
 968:    * @deprecated unsafe operation, try not to use
 969:    */
 970:   public final native void stop(Throwable t);
 971: 
 972:   /**
 973:    * Suspend this Thread.  It will not come back, ever, unless it is resumed.
 974:    *
 975:    * <p>This is inherently unsafe, as the suspended thread still holds locks,
 976:    * and can potentially deadlock your program.  Hence, there is a security
 977:    * check: <code>checkAccess</code>.
 978:    *
 979:    * @throws SecurityException if you cannot suspend the Thread
 980:    * @see #checkAccess()
 981:    * @see #resume()
 982:    * @deprecated unsafe operation, try not to use
 983:    */
 984:   public final native void suspend();
 985: 
 986:   /**
 987:    * Set this Thread's priority. There may be a security check,
 988:    * <code>checkAccess</code>, then the priority is set to the smaller of
 989:    * priority and the ThreadGroup maximum priority.
 990:    *
 991:    * @param priority the new priority for this Thread
 992:    * @throws IllegalArgumentException if priority exceeds MIN_PRIORITY or
 993:    *         MAX_PRIORITY
 994:    * @throws SecurityException if you cannot modify this Thread
 995:    * @see #getPriority()
 996:    * @see #checkAccess()
 997:    * @see ThreadGroup#getMaxPriority()
 998:    * @see #MIN_PRIORITY
 999:    * @see #MAX_PRIORITY
1000:    */
1001:   public final native void setPriority(int newPriority);
1002: 
1003:   /**
1004:    * Returns a string representation of this thread, including the
1005:    * thread's name, priority, and thread group.
1006:    *
1007:    * @return a human-readable String representing this Thread
1008:    */
1009:   public String toString()
1010:   {
1011:     return ("Thread[" + name + "," + priority + ","
1012:         + (group == null ? "" : group.getName()) + "]");
1013:   }
1014: 
1015:   private final native void initialize_native();
1016: 
1017:   private final native static String gen_name();
1018: 
1019:   /**
1020:    * Returns the map used by ThreadLocal to store the thread local values.
1021:    */
1022:   static Map getThreadLocals()
1023:   {
1024:     Thread thread = currentThread();
1025:     Map locals = thread.locals;
1026:     if (locals == null)
1027:       {
1028:         locals = thread.locals = new WeakIdentityHashMap();
1029:       }
1030:     return locals;
1031:   }
1032: 
1033:   /** 
1034:    * Assigns the given <code>UncaughtExceptionHandler</code> to this
1035:    * thread.  This will then be called if the thread terminates due
1036:    * to an uncaught exception, pre-empting that of the
1037:    * <code>ThreadGroup</code>.
1038:    *
1039:    * @param h the handler to use for this thread.
1040:    * @throws SecurityException if the current thread can't modify this thread.
1041:    * @since 1.5 
1042:    */
1043:   public void setUncaughtExceptionHandler(UncaughtExceptionHandler h)
1044:   {
1045:     SecurityManager sm = SecurityManager.current; // Be thread-safe.
1046:     if (sm != null)
1047:       sm.checkAccess(this);    
1048:     exceptionHandler = h;
1049:   }
1050: 
1051:   /** 
1052:    * <p>
1053:    * Returns the handler used when this thread terminates due to an
1054:    * uncaught exception.  The handler used is determined by the following:
1055:    * </p>
1056:    * <ul>
1057:    * <li>If this thread has its own handler, this is returned.</li>
1058:    * <li>If not, then the handler of the thread's <code>ThreadGroup</code>
1059:    * object is returned.</li>
1060:    * <li>If both are unavailable, then <code>null</code> is returned
1061:    *     (which can only happen when the thread was terminated since
1062:    *      then it won't have an associated thread group anymore).</li>
1063:    * </ul>
1064:    * 
1065:    * @return the appropriate <code>UncaughtExceptionHandler</code> or
1066:    *         <code>null</code> if one can't be obtained.
1067:    * @since 1.5 
1068:    */
1069:   public UncaughtExceptionHandler getUncaughtExceptionHandler()
1070:   {
1071:     // FIXME: if thread is dead, should return null...
1072:     return exceptionHandler != null ? exceptionHandler : group;
1073:   }
1074: 
1075:   /** 
1076:    * <p>
1077:    * Sets the default uncaught exception handler used when one isn't
1078:    * provided by the thread or its associated <code>ThreadGroup</code>.
1079:    * This exception handler is used when the thread itself does not
1080:    * have an exception handler, and the thread's <code>ThreadGroup</code>
1081:    * does not override this default mechanism with its own.  As the group
1082:    * calls this handler by default, this exception handler should not defer
1083:    * to that of the group, as it may lead to infinite recursion.
1084:    * </p>
1085:    * <p>
1086:    * Uncaught exception handlers are used when a thread terminates due to
1087:    * an uncaught exception.  Replacing this handler allows default code to
1088:    * be put in place for all threads in order to handle this eventuality.
1089:    * </p>
1090:    *
1091:    * @param h the new default uncaught exception handler to use.
1092:    * @throws SecurityException if a security manager is present and
1093:    *                           disallows the runtime permission
1094:    *                           "setDefaultUncaughtExceptionHandler".
1095:    * @since 1.5 
1096:    */
1097:   public static void 
1098:     setDefaultUncaughtExceptionHandler(UncaughtExceptionHandler h)
1099:   {
1100:     SecurityManager sm = SecurityManager.current; // Be thread-safe.
1101:     if (sm != null)
1102:       sm.checkPermission(new RuntimePermission("setDefaultUncaughtExceptionHandler"));    
1103:     defaultHandler = h;
1104:   }
1105: 
1106:   /** 
1107:    * Returns the handler used by default when a thread terminates
1108:    * unexpectedly due to an exception, or <code>null</code> if one doesn't
1109:    * exist.
1110:    *
1111:    * @return the default uncaught exception handler.
1112:    * @since 1.5 
1113:    */
1114:   public static UncaughtExceptionHandler getDefaultUncaughtExceptionHandler()
1115:   {
1116:     return defaultHandler;
1117:   }
1118:   
1119:   /** 
1120:    * Returns the unique identifier for this thread.  This ID is generated
1121:    * on thread creation, and may be re-used on its death.
1122:    *
1123:    * @return a positive long number representing the thread's ID.
1124:    * @since 1.5 
1125:    */
1126:   public long getId()
1127:   {
1128:     return threadId;
1129:   }
1130: 
1131:   /**
1132:    * <p>
1133:    * This interface is used to handle uncaught exceptions
1134:    * which cause a <code>Thread</code> to terminate.  When
1135:    * a thread, t, is about to terminate due to an uncaught
1136:    * exception, the virtual machine looks for a class which
1137:    * implements this interface, in order to supply it with
1138:    * the dying thread and its uncaught exception.
1139:    * </p>
1140:    * <p>
1141:    * The virtual machine makes two attempts to find an
1142:    * appropriate handler for the uncaught exception, in
1143:    * the following order:
1144:    * </p>
1145:    * <ol>
1146:    * <li>
1147:    * <code>t.getUncaughtExceptionHandler()</code> --
1148:    * the dying thread is queried first for a handler
1149:    * specific to that thread.
1150:    * </li>
1151:    * <li>
1152:    * <code>t.getThreadGroup()</code> --
1153:    * the thread group of the dying thread is used to
1154:    * handle the exception.  If the thread group has
1155:    * no special requirements for handling the exception,
1156:    * it may simply forward it on to
1157:    * <code>Thread.getDefaultUncaughtExceptionHandler()</code>,
1158:    * the default handler, which is used as a last resort.
1159:    * </li>
1160:    * </ol>
1161:    * <p>
1162:    * The first handler found is the one used to handle
1163:    * the uncaught exception.
1164:    * </p>
1165:    *
1166:    * @author Tom Tromey <tromey@redhat.com>
1167:    * @author Andrew John Hughes <gnu_andrew@member.fsf.org>
1168:    * @since 1.5
1169:    * @see Thread#getUncaughtExceptionHandler()
1170:    * @see Thread#setUncaughtExceptionHandler(UncaughtExceptionHandler)
1171:    * @see Thread#getDefaultUncaughtExceptionHandler()
1172:    * @see
1173:    * Thread#setDefaultUncaughtExceptionHandler(java.lang.Thread.UncaughtExceptionHandler)
1174:    */
1175:   public interface UncaughtExceptionHandler
1176:   {
1177:     /**
1178:      * Invoked by the virtual machine with the dying thread
1179:      * and the uncaught exception.  Any exceptions thrown
1180:      * by this method are simply ignored by the virtual
1181:      * machine.
1182:      *
1183:      * @param thr the dying thread.
1184:      * @param exc the uncaught exception.
1185:      */
1186:     void uncaughtException(Thread thr, Throwable exc);
1187:   }
1188: 
1189:   /** 
1190:    * <p>
1191:    * Represents the current state of a thread, according to the VM rather
1192:    * than the operating system.  It can be one of the following:
1193:    * </p>
1194:    * <ul>
1195:    * <li>NEW -- The thread has just been created but is not yet running.</li>
1196:    * <li>RUNNABLE -- The thread is currently running or can be scheduled
1197:    * to run.</li>
1198:    * <li>BLOCKED -- The thread is blocked waiting on an I/O operation
1199:    * or to obtain a lock.</li>
1200:    * <li>WAITING -- The thread is waiting indefinitely for another thread
1201:    * to do something.</li>
1202:    * <li>TIMED_WAITING -- The thread is waiting for a specific amount of time
1203:    * for another thread to do something.</li>
1204:    * <li>TERMINATED -- The thread has exited.</li>
1205:    * </ul>
1206:    *
1207:    * @since 1.5 
1208:    */
1209:   public enum State
1210:   {
1211:     BLOCKED, NEW, RUNNABLE, TERMINATED, TIMED_WAITING, WAITING;
1212:   }
1213: 
1214: 
1215:   /**
1216:    * Returns the current state of the thread.  This
1217:    * is designed for monitoring thread behaviour, rather
1218:    * than for synchronization control.
1219:    *
1220:    * @return the current thread state.
1221:    */
1222:   public native State getState();
1223: 
1224:   /**
1225:    * <p>
1226:    * Returns a map of threads to stack traces for each
1227:    * live thread.  The keys of the map are {@link Thread}
1228:    * objects, which map to arrays of {@link StackTraceElement}s.
1229:    * The results obtained from Calling this method are
1230:    * equivalent to calling {@link getStackTrace()} on each
1231:    * thread in succession.  Threads may be executing while
1232:    * this takes place, and the results represent a snapshot
1233:    * of the thread at the time its {@link getStackTrace()}
1234:    * method is called.
1235:    * </p>
1236:    * <p>
1237:    * The stack trace information contains the methods called
1238:    * by the thread, with the most recent method forming the
1239:    * first element in the array.  The array will be empty
1240:    * if the virtual machine can not obtain information on the
1241:    * thread. 
1242:    * </p>
1243:    * <p>
1244:    * To execute this method, the current security manager
1245:    * (if one exists) must allow both the
1246:    * <code>"getStackTrace"</code> and
1247:    * <code>"modifyThreadGroup"</code> {@link RuntimePermission}s.
1248:    * </p>
1249:    * 
1250:    * @return a map of threads to arrays of {@link StackTraceElement}s.
1251:    * @throws SecurityException if a security manager exists, and
1252:    *                           prevents either or both the runtime
1253:    *                           permissions specified above.
1254:    * @since 1.5
1255:    * @see #getStackTrace()
1256:    */
1257:   public static Map<Thread, StackTraceElement[]> getAllStackTraces()
1258:   {
1259:     ThreadGroup group = currentThread().group;
1260:     while (group.getParent() != null)
1261:       group = group.getParent();
1262:     int arraySize = group.activeCount();
1263:     Thread[] threadList = new Thread[arraySize];
1264:     int filled = group.enumerate(threadList);
1265:     while (filled == arraySize)
1266:       {
1267:     arraySize *= 2;
1268:     threadList = new Thread[arraySize];
1269:     filled = group.enumerate(threadList);
1270:       }
1271:     Map traces = new HashMap();
1272:     for (int a = 0; a < filled; ++a)
1273:       traces.put(threadList[a],
1274:          threadList[a].getStackTrace());
1275:     return traces;
1276:   }
1277: 
1278:   /**
1279:    * <p>
1280:    * Returns an array of {@link StackTraceElement}s
1281:    * representing the current stack trace of this thread.
1282:    * The first element of the array is the most recent
1283:    * method called, and represents the top of the stack.
1284:    * The elements continue in this order, with the last
1285:    * element representing the bottom of the stack.
1286:    * </p>
1287:    * <p>
1288:    * A zero element array is returned for threads which
1289:    * have not yet started (and thus have not yet executed
1290:    * any methods) or for those which have terminated.
1291:    * Where the virtual machine can not obtain a trace for
1292:    * the thread, an empty array is also returned.  The
1293:    * virtual machine may also omit some methods from the
1294:    * trace in non-zero arrays.
1295:    * </p>
1296:    * <p>
1297:    * To execute this method, the current security manager
1298:    * (if one exists) must allow both the
1299:    * <code>"getStackTrace"</code> and
1300:    * <code>"modifyThreadGroup"</code> {@link RuntimePermission}s.
1301:    * </p>
1302:    *
1303:    * @return a stack trace for this thread.
1304:    * @throws SecurityException if a security manager exists, and
1305:    *                           prevents the use of the
1306:    *                           <code>"getStackTrace"</code>
1307:    *                           permission.
1308:    * @since 1.5
1309:    * @see #getAllStackTraces()
1310:    */
1311:   public StackTraceElement[] getStackTrace()
1312:   {
1313:     SecurityManager sm = SecurityManager.current; // Be thread-safe.
1314:     if (sm != null)
1315:       sm.checkPermission(new RuntimePermission("getStackTrace"));
1316: 
1317:     // Calling java.lang.management via reflection means that
1318:     // javax.management be overridden in the endorsed directory.
1319: 
1320:     // This is the equivalent code:
1321:     //
1322:     //     ThreadMXBean bean = ManagementFactory.getThreadMXBean();
1323:     //     ThreadInfo info = bean.getThreadInfo(getId(), Integer.MAX_VALUE);
1324:     //     return info.getStackTrace();
1325: 
1326:     try
1327:       {
1328:     try
1329:       {
1330:         Object bean 
1331:           = (Class.forName("java.lang.management.ManagementFactory")
1332:          .getDeclaredMethod("getThreadMXBean")
1333:          .invoke(null));
1334:         Object info = bean.getClass()
1335:           .getDeclaredMethod("getThreadInfo", long.class, int.class)
1336:           .invoke(bean, new Long(getId()), new Integer(Integer.MAX_VALUE));
1337:         Object trace = info.getClass()
1338:           .getDeclaredMethod("getStackTrace").invoke(info);
1339:         return (StackTraceElement[])trace;
1340:       }
1341:     catch (InvocationTargetException e)
1342:       {
1343:         throw (Exception)e.getTargetException();
1344:       }
1345:       }
1346:     catch (UnsupportedOperationException e)
1347:       {
1348:     throw e;
1349:       }
1350:     catch (Exception e)
1351:       {
1352:     throw new UnsupportedOperationException(e);
1353:       }
1354:   }
1355: }