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