Re: Request for change to vm/reference/java/lang/Thread.java

[Mark Wielaard]

Hi,

On Wed, 2002-09-11 at 15:16, Stephen Crawley wrote:
> 
> To get this to work in Kissme, I made some changes to the constructor
> that explicitly deal with the case where currentThread returns null,
> and sets the priority, thread group and daemon flag appropriately.
> 
> The changes are below.  Could they be back-fitted to the Classpath
> reference implementation of Thread.java please?

I agree that these changes make the constructor more robust and have
checked them in.

I have been thinking about splitting out the VM dependent parts of
Thread from the general parts and have come up with the attached
VMThread interface.

I have not yet completely finished rewriting Thread based on this VM
interface but I think I got the design correct. Thread will get the
following 'callbacks' that can be used by the VM from the native
VMThread.start() method and/or the JNI invocation methods:

/**
 * Should be called from the VMThread.start() implementation.
 * Automatically handles all Thread state transitions, running the
 * correct Runnable and shutting down the VM after the last user Thread
 * stops.
 */
private static void startRun(Thread t)

/**
 * Sets the state of the Thread. Can be CREATED, RUNNING, SUSPENDED
 * or FINISHED. Throws an IllegalStateException when an illegal state
 * transition is made.
 * <p>
 * The VM should only call this just after creating the Thread on a
 * JNI_CreateVM() or AttachCurrentThread[AsDeamon]() with state RUNNING.
 * And on a JNI_DetachCurrentThread() or JNI_DestroyVM() it should call
 * the method with state FINISHED. JNI_DestroyVM has to call the
 * callback waitForShutDown() after that to wait for all other user
 * Threads to stop.
 * <p>
 * The implementation of VMThread.start() should call the method
 * startRun() that will automatically handle all state transitions.
 */
private void setState(int state) throws IllegalStateException

/**
 * Handles an uncaught exception that terminates a Thread.
 * Automatically called from startRun(). Should be called by the VM
 * when a Thread that was not started through startRun() doesn't handle
 * a thrown exception. After calling this method the Thread should stop
 * executing after a last call to setState(FINISHED).
 */
private void uncaughtException(Throwable t)

/**
 * Should be called by the VM after a JNI_DestroyVM() to make sure all
 * user Threads have been stopped.
 */
private static void waitForShutdown()

I will try to make this work with one of the VMs based on Classpath and
maybe gcj to see if the design makes sense and if I made some bad
assumptions. But if someone has comments, questions or suggestions now
please let me know.

Cheers,

Mark

-- 
No.
> Should I include quotations after my reply?

/* VMThread -- VM interface for Thread of executable code
   Copyright (C) 2002 Free Software Foundation

This file is part of GNU Classpath.

GNU Classpath is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.

GNU Classpath is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with GNU Classpath; see the file COPYING.  If not, write to the
Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
02111-1307 USA.

Linking this library statically or dynamically with other modules is
making a combined work based on this library.  Thus, the terms and
conditions of the GNU General Public License cover the whole
combination.

As a special exception, the copyright holders of this library give you
permission to link this library with independent modules to produce an
executable, regardless of the license terms of these independent
modules, and to copy and distribute the resulting executable under
terms of your choice, provided that you also meet, for each linked
independent module, the terms and conditions of the license of that
module.  An independent module is a module which is not derived from
or based on this library.  If you modify this library, you may extend
this exception to your version of the library, but you are not
obligated to do so.  If you do not wish to do so, delete this
exception statement from your version. */

package java.lang;

/**
 * VM interface for Thread of executable code. Holds VM dependant state.
 * It is deliberately package local and final and should only be accessed
 * by the Thread class.
 * <p>
 * This is the GNU Classpath reference implementation, it should be adapted
 * for a specific VM.
 * <p>
 * The following methods must be implemented:
 * <ul>
 * <li>native void start();
 * <li>native boolean interrupt();
 * <li>native static VMThread current();
 * </ul>
 * All other methods may be implemented to make Thread handling more efficient
 * or to implement some optional (and sometimes deprecated) behaviour. Default
 * implementations are provided but it is highly recommended to optimize them
 * for a specific VM.
 * 
 * @author Mark Wielaard (address@hidden)
 */
final class VMThread
{
  /**
   * The Thread object that this VM state belongs to.
   * Used in currentThread() and start().
   */
  private final Thread thread;

  /**
   * Private constructor, create VMThreads with the static create method.
   *
   * @param thread The Thread object that was just created.
   */
  private VMThread(Thread thread)
  {
    this.thread = thread;
  }

  /**
   * Creates a native Thread. This is called from the contructor of Thread.
   * The Thread is not yet started.
   *
   * @param thread The newly created Thread object
   * @param stack Indicates the requested stacksize. Normally zero, non-zero
   * values indicate requested stack size in bytes but it is up to the
   * specific VM implementation to interpret them and may be ignored.
   */
  static VMThread create(Thread thread, int stack)
  {
    // ignore stack size.
    return new VMThread(thread);
  }

  /**
   * Disposes of the native Thread state. This is called when the Thread is
   * going in the FINISHED state or when it is garbage collected.
   * It will be called only once after which all references to this object
   * will be disposed.
   * <p>
   * Note that it will normally be called from the currently executing Thread
   * as one of the last instructions before the it actually ends. The Thread
   * object may still be around for some time but none of the methods of
   * this VMThread object will be called after this.
   */
  void dispose() { }

  /**
   * Actually starts running the new thread.
   * Should start executing the thread by calling <code>Thread.startRun()</code>
   * with as argument the associated Thread object of this VMThread.
   * The <code>startRun()</code> method makes sure the Thread state is handled
   * correctly, runs the correct <code>run()</code> method and handles all
   * uncaught exceptions.
   */
  native void start();

  /**
   * Interrupt this Thread.
   * Will always be called from another execution Thread.
   * If the thread is blocked in a Object.wait() call then the Thread should
   * be waken up, by a <code>InterruptedException</code> and this method
   * should return true. Otherwise this method can just return false.
   *
   * XXX - Not yet decided how to handle I/O interruption. Will probably
   * be handled by the GNU Classpath Thread.interrupt() method and the native
   * i/o library.
   */
  native boolean interrupt();

  /**
   * Get the currently executing Thread.
   * May return null during bootstrapping only when the first Thread object is
   * created.
   */
  static Thread currentThread()
  {
    VMThread current = current();
    return current != null ? current.thread : null;
  }

  /**
   * Returns the VMThread object associated with the current executing Thread.
   * May return null, but this should only happen during bootstrapping.
   */
  static native VMThread current();

  /**
   * Sets the priority of the Thread.
   * The given priority will be between 1 (low) and 10 (high) inclusive and
   * will normally be 5. It is up to the VM implementation to interpret what
   * this means for the actual Thread scheduling. It might be ignored.
   * May be called before or after the Thread is acutally started.
   */
  void setPriority(int priority) { }

  /**
   * Request to give some other executing threads some extra time.
   * Might give some extra time to some other executing threads before
   * returning from this method to the currently executing thread.
   */
  static void yield() { }

  /**
   * Checks whether the current thread holds the monitor on a given object.
   * Returns true if the current thread is currently synchronized on obj,
   * otherwise false. Will never be called with a null obj.
   */
  static boolean holdsLock(Object obj)
  {
    // Just try to wait on the object for a very short time which can only
    // be done if we actually have the object monitor lock.
    // Can be implemented more safely and efficiently by a native VM method.
    try
      {
        obj.wait(0,1);
        return true;
      }
    catch (IllegalMonitorStateException imse)
      {
        return false;
      }
    catch (InterruptedException ie)
      {
        // Oops, better make sure the Thread is interrupted again since
        // the wait() has cleared the interrupt flag.
        currentThread().interrupt();
        return true;
      }
  }

  // DEPRECATED METHODS

  /**
   * Cause the Thread to stop abnormally by throwing the specified exception.
   *
   * @param t the non-null Throwable to throw, normally a ThreadDeath
   * @deprecated unsafe operation
   */
  void stop(Throwable throwable) { }

  /**
   * Suspend the Thread till resume is called.
   * Returns true if the VM actually suspended the Thread.
   * It is not recommended that VMs actually support this method since it
   * is unsafe when the Thread still holds locks while suspended.
   *
   * @deprecated unsafe operation
   */
  boolean suspend()
  {
    return false;
  }

  /**
   * Resume this Thread.
   * Will only be called if a previous call to suspend() returned true.
   *
   * @deprecated unsafe operation
   */
  void resume() { }

  /**
   * Returns the number of stack frames in this Thread.
   * Will only be called when when a previous call to suspend() returned true.
   *
   * @deprecated unsafe operation
   */
  public int countStackFrames()
  {
    return 0;
  }

}