gomp-20050608-branch/libjava/classpath/vm/reference/java/lang/VMThread.java

   1 /* VMThread -- VM interface for Thread of executable code
   2    Copyright (C) 2003, 2004, 2005 Free Software Foundation
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38 package java.lang;
  39
  40 /**
  41  * VM interface for Thread of executable code. Holds VM dependent state.
  42  * It is deliberately package local and final and should only be accessed
  43  * by the Thread class.
  44  * <p>
  45  * This is the GNU Classpath reference implementation, it should be adapted
  46  * for a specific VM.
  47  * <p>
  48  * The following methods must be implemented:
  49  * <ul>
  50  * <li>native void start(long stacksize);
  51  * <li>native void interrupt();
  52  * <li>native boolean isInterrupted();
  53  * <li>native void suspend();
  54  * <li>native void resume();
  55  * <li>native void nativeSetPriority(int priority);
  56  * <li>native void nativeStop(Throwable t);
  57  * <li>native static Thread currentThread();
  58  * <li>static native void yield();
  59  * <li>static native boolean interrupted();
  60  * </ul>
  61  * All other methods may be implemented to make Thread handling more efficient
  62  * or to implement some optional (and sometimes deprecated) behaviour. Default
  63  * implementations are provided but it is highly recommended to optimize them
  64  * for a specific VM.
  65  *
  66  * @author Jeroen Frijters (jeroen@frijters.net)
  67  * @author Dalibor Topic (robilad@kaffe.org)
  68  */
  69 final class VMThread
  70 {
  71     /**
  72      * The Thread object that this VM state belongs to.
  73      * Used in currentThread() and start().
  74      * Note: when this thread dies, this reference is *not* cleared
  75      */
  76     volatile Thread thread;
  77
  78     /**
  79      * Flag that is set when the thread runs, used by stop() to protect against
  80      * stop's getting lost.
  81      */
  82     private volatile boolean running;
  83
  84     /**
  85      * VM private data.
  86      */
  87     private transient Object vmdata;
  88
  89     /**
  90      * Private constructor, create VMThreads with the static create method.
  91      *
  92      * @param thread The Thread object that was just created.
  93      */
  94     private VMThread(Thread thread)
  95     {
  96         this.thread = thread;
  97     }
  98
  99     /**
 100      * This method is the initial Java code that gets executed when a native
 101      * thread starts. It's job is to coordinate with the rest of the VMThread
 102      * logic and to start executing user code and afterwards handle clean up.
 103      */
 104     private void run()
 105     {
 106         try
 107         {
 108             try
 109             {
 110                 running = true;
 111                 synchronized(thread)
 112                 {
 113                     Throwable t = thread.stillborn;
 114                     if(t != null)
 115                     {
 116                         thread.stillborn = null;
 117                         throw t;
 118                     }
 119                 }
 120                 thread.run();
 121             }
 122             catch(Throwable t)
 123             {
 124                 try
 125                 {
 126                     thread.group.uncaughtException(thread, t);
 127                 }
 128                 catch(Throwable ignore)
 129                 {
 130                 }
 131             }
 132         }
 133         finally
 134         {
 135             // Setting runnable to false is partial protection against stop
 136             // being called while we're cleaning up. To be safe all code in
 137             // VMThread be unstoppable.
 138             running = false;
 139             thread.die();
 140             synchronized(this)
 141             {
 142                 // release the threads waiting to join us
 143                 notifyAll();
 144             }
 145         }
 146     }
 147
 148     /**
 149      * Creates a native Thread. This is called from the start method of Thread.
 150      * The Thread is started.
 151      *
 152      * @param thread The newly created Thread object
 153      * @param stacksize Indicates the requested stacksize. Normally zero,
 154      * non-zero values indicate requested stack size in bytes but it is up
 155      * to the specific VM implementation to interpret them and may be ignored.
 156      */
 157     static void create(Thread thread, long stacksize)
 158     {
 159         VMThread vmThread = new VMThread(thread);
 160         vmThread.start(stacksize);
 161         thread.vmThread = vmThread;
 162     }
 163
 164     /**
 165      * Gets the name of the thread. Usually this is the name field of the
 166      * associated Thread object, but some implementation might choose to
 167      * return the name of the underlying platform thread.
 168      */
 169     String getName()
 170     {
 171         return thread.name;
 172     }
 173
 174     /**
 175      * Set the name of the thread. Usually this sets the name field of the
 176      * associated Thread object, but some implementations might choose to
 177      * set the name of the underlying platform thread.
 178      * @param name The new name
 179      */
 180     void setName(String name)
 181     {
 182         thread.name = name;
 183     }
 184
 185     /**
 186      * Set the thread priority field in the associated Thread object and
 187      * calls the native method to set the priority of the underlying
 188      * platform thread.
 189      * @param priority The new priority
 190      */
 191     void setPriority(int priority)
 192     {
 193         thread.priority = priority;
 194         nativeSetPriority(priority);
 195     }
 196
 197     /**
 198      * Returns the priority. Usually this is the priority field from the
 199      * associated Thread object, but some implementation might choose to
 200      * return the priority of the underlying platform thread.
 201      * @return this Thread's priority
 202      */
 203     int getPriority()
 204     {
 205         return thread.priority;
 206     }
 207
 208     /**
 209      * Returns true if the thread is a daemon thread. Usually this is the
 210      * daemon field from the associated Thread object, but some
 211      * implementation might choose to return the daemon state of the underlying
 212      * platform thread.
 213      * @return whether this is a daemon Thread or not
 214      */
 215     boolean isDaemon()
 216     {
 217         return thread.daemon;
 218     }
 219
 220     /**
 221      * Returns the number of stack frames in this Thread.
 222      * Will only be called when when a previous call to suspend() returned true.
 223      *
 224      * @deprecated unsafe operation
 225      */
 226     native int countStackFrames();
 227
 228     /**
 229      * Wait the specified amount of time for the Thread in question to die.
 230      *
 231      * <p>Note that 1,000,000 nanoseconds == 1 millisecond, but most VMs do
 232      * not offer that fine a grain of timing resolution. Besides, there is
 233      * no guarantee that this thread can start up immediately when time expires,
 234      * because some other thread may be active.  So don't expect real-time
 235      * performance.
 236      *
 237      * @param ms the number of milliseconds to wait, or 0 for forever
 238      * @param ns the number of extra nanoseconds to sleep (0-999999)
 239      * @throws InterruptedException if the Thread is interrupted; it's
 240      *         <i>interrupted status</i> will be cleared
 241      */
 242     synchronized void join(long ms, int ns) throws InterruptedException
 243     {
 244         // Round up
 245         ms += (ns != 0) ? 1 : 0;
 246
 247         // Compute end time, but don't overflow
 248         long now = System.currentTimeMillis();
 249         long end = now + ms;
 250         if (end < now)
 251             end = Long.MAX_VALUE;
 252
 253         // A VM is allowed to return from wait() without notify() having been
 254         // called, so we loop to handle possible spurious wakeups.
 255         while(thread.vmThread != null)
 256         {
 257             // We use the VMThread object to wait on, because this is a private
 258             // object, so client code cannot call notify on us.
 259             wait(ms);
 260             if(ms != 0)
 261             {
 262                 now = System.currentTimeMillis();
 263                 ms = end - now;
 264                 if(ms <= 0)
 265                 {
 266                     break;
 267                 }
 268             }
 269         }
 270     }
 271
 272     /**
 273      * Cause this Thread to stop abnormally and throw the specified exception.
 274      * If you stop a Thread that has not yet started, the stop is ignored
 275      * (contrary to what the JDK documentation says).
 276      * <b>WARNING</b>This bypasses Java security, and can throw a checked
 277      * exception which the call stack is unprepared to handle. Do not abuse
 278      * this power.
 279      *
 280      * <p>This is inherently unsafe, as it can interrupt synchronized blocks and
 281      * leave data in bad states.
 282      *
 283      * <p><b>NOTE</b> stop() should take care not to stop a thread if it is
 284      * executing code in this class.
 285      *
 286      * @param t the Throwable to throw when the Thread dies
 287      * @deprecated unsafe operation, try not to use
 288      */
 289     void stop(Throwable t)
 290     {
 291         // Note: we assume that we own the lock on thread
 292         // (i.e. that Thread.stop() is synchronized)
 293         if(running)
 294             nativeStop(t);
 295         else
 296             thread.stillborn = t;
 297     }
 298
 299     /**
 300      * Create a native thread on the underlying platform and start it executing
 301      * on the run method of this object.
 302      * @param stacksize the requested size of the native thread stack
 303      */
 304     native void start(long stacksize);
 305
 306     /**
 307      * Interrupt this thread.
 308      */
 309     native void interrupt();
 310
 311     /**
 312      * Determine whether this Thread has been interrupted, but leave
 313      * the <i>interrupted status</i> alone in the process.
 314      *
 315      * @return whether the Thread has been interrupted
 316      */
 317     native boolean isInterrupted();
 318
 319     /**
 320      * Suspend this Thread.  It will not come back, ever, unless it is resumed.
 321      */
 322     native void suspend();
 323
 324     /**
 325      * Resume this Thread.  If the thread is not suspended, this method does
 326      * nothing.
 327      */
 328     native void resume();
 329
 330     /**
 331      * Set the priority of the underlying platform thread.
 332      *
 333      * @param priority the new priority
 334      */
 335     native void nativeSetPriority(int priority);
 336
 337     /**
 338      * Asynchronously throw the specified throwable in this Thread.
 339      *
 340      * @param t the exception to throw
 341      */
 342     native void nativeStop(Throwable t);
 343
 344     /**
 345      * Return the Thread object associated with the currently executing
 346      * thread.
 347      *
 348      * @return the currently executing Thread
 349      */
 350     static native Thread currentThread();
 351
 352     /**
 353      * Yield to another thread. The Thread will not lose any locks it holds
 354      * during this time. There are no guarantees which thread will be
 355      * next to run, and it could even be this one, but most VMs will choose
 356      * the highest priority thread that has been waiting longest.
 357      */
 358     static native void yield();
 359
 360     /**
 361      * Suspend the current Thread's execution for the specified amount of
 362      * time. The Thread will not lose any locks it has during this time. There
 363      * are no guarantees which thread will be next to run, but most VMs will
 364      * choose the highest priority thread that has been waiting longest.
 365      *
 366      * <p>Note that 1,000,000 nanoseconds == 1 millisecond, but most VMs do
 367      * not offer that fine a grain of timing resolution. Besides, there is
 368      * no guarantee that this thread can start up immediately when time expires,
 369      * because some other thread may be active.  So don't expect real-time
 370      * performance.
 371      *
 372      * @param ms the number of milliseconds to sleep.
 373      * @param ns the number of extra nanoseconds to sleep (0-999999)
 374      * @throws InterruptedException if the Thread is (or was) interrupted;
 375      *         it's <i>interrupted status</i> will be cleared
 376      */
 377     static void sleep(long ms, int ns) throws InterruptedException
 378     {
 379       // Note: JDK treats a zero length sleep is like Thread.yield(),
 380       // without checking the interrupted status of the thread.
 381       // It's unclear if this is a bug in the implementation or the spec.
 382       // See http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6213203
 383       if (ms == 0 && ns == 0)
 384         {
 385           if (Thread.interrupted())
 386             throw new InterruptedException();
 387           return;
 388         }
 389
 390       // Compute end time, but don't overflow
 391       long now = System.currentTimeMillis();
 392       long end = now + ms;
 393       if (end < now)
 394           end = Long.MAX_VALUE;
 395
 396       // A VM is allowed to return from wait() without notify() having been
 397       // called, so we loop to handle possible spurious wakeups.
 398       VMThread vt = Thread.currentThread().vmThread;
 399       synchronized (vt)
 400         {
 401           while (true)
 402             {
 403               vt.wait(ms, ns);
 404               now = System.currentTimeMillis();
 405               if (now >= end)
 406                 break;
 407               ms = end - now;
 408               ns = 0;
 409             }
 410         }
 411     }
 412
 413     /**
 414      * Determine whether the current Thread has been interrupted, and clear
 415      * the <i>interrupted status</i> in the process.
 416      *
 417      * @return whether the current Thread has been interrupted
 418      */
 419     static native boolean interrupted();
 420
 421     /**
 422      * Checks whether the current thread holds the monitor on a given object.
 423      * This allows you to do <code>assert Thread.holdsLock(obj)</code>.
 424      *
 425      * @param obj the object to check
 426      * @return true if the current thread is currently synchronized on obj
 427      * @throws NullPointerException if obj is null
 428      */
 429     static boolean holdsLock(Object obj)
 430     {
 431       /* Use obj.notify to check if the current thread holds
 432        * the monitor of the object.
 433        * If it doesn't, notify will throw an exception.
 434        */
 435       try
 436         {
 437           obj.notify();
 438           // okay, current thread holds lock
 439           return true;
 440         }
 441       catch (IllegalMonitorStateException e)
 442         {
 443           // it doesn't hold the lock
 444           return false;
 445         }
 446     }
 447 }