// ************************************************************************
//    $Id: NoHeapRealtimeThread.java 594 2005-07-22 03:03:58Z mdeters $
// ************************************************************************
//
//                                jRate
//
//               Copyright (C) 2001-2005 by Angelo Corsaro.
//                         <corsaro@cse.wustl.edu>
//                          All Rights Reserved.
//
//   Permission to use, copy, modify, and distribute this software and
//   its  documentation for any purpose is hereby  granted without fee,
//   provided that the above copyright notice appear in all copies and
//   that both that copyright notice and this permission notice appear
//   in  supporting  documentation. I don't make  any  representations
//   about the  suitability  of this  software for any  purpose. It is
//   provided "as is" without express or implied warranty.
//
//
// *************************************************************************
//
// *************************************************************************

package javax.realtime;

/**
 * A <code>NoHeapRealtimeThread</code> is a specialized form of {@link
 * RealtimeThread}. Because an instance of
 * <code>NoHeapRealtimeThread</code> may immediately preempt any
 * implemented garbage collector logic contained in its
 * <code>run()</code> is never allowed to allocate or reference any
 * object allocated in the heap nor is it even allowed to manipulate
 * any reference toany object in the heap. For example, if a and b are
 * objects in immortal memory, b.p is reference to an object on the
 * heap, and a.p is type compatible with b.p, then a
 * NoHeapRealtimeThread is not allowed to execute anything like the
 * following: <p>
 * <code>
 *               a.p = b.p; b.p = null;
 * </code><p>
 *
 * Thus,it is always safe for a <code>NoHeapRealtimeThread</code> to
 * interrupt the garbage collector at any time, without waiting for
 * the end of the garbage collection cycle or a defined preemption
 * point. Due to these restrictions, a
 * <code>NoHeapRealtimeThread</code> object must be placed in a memory
 * area such that thread logic may unexceptionally access instance
 * variables and such that Java methods on {@link java.lang.Thread}
 * (e.g., enumerate and join) complete normally except where execution
 * would cause access violations. The constructors of
 * <code>NoHeapRealtimeThread</code> require a reference to {@link
 * ScopedMemory} or {@link ImmortalMemory} . When the thread is
 * started, all execution occurs in the scope of the given memory
 * area. Thus, all memory allocation performed with the new operator
 * is taken from this given area. Parameters for constructors may be
 * null . In such cases the default value will be the default value
 * set for the particular type by the associated instance of {@link
 * Scheduler}.
 *
 * @author <a href="mailto:corsaro@cse.wustl.edu">Angelo Corsaro</a>
 * @version 1.0
 */
public class NoHeapRealtimeThread extends RealtimeThread {

    /**
     * Creates a new <code>NoHeapRealtimeThread</code> instance with the
     * given characteristics.
     *
     * @param schedulingParam The {@link SchedulingParameters}
     * associated with this (and possibly other instances of
     * <code>NoHeapRealtimeThread<code>).
     * @param memoryArea The {@link MemoryArea} associated with this.
     */
    public NoHeapRealtimeThread(SchedulingParameters schedulingParam,
                                MemoryArea memoryArea)
        throws IllegalArgumentException {
        this(schedulingParam,
             null,
             null,
             memoryArea,
             null,
             null);
    }

    /**
     * Creates a new <code>NoHeapRealtimeThread</code> instance with the
     * given characteristics and a <code>java.lang.Runnable</code>.
     *
     * @param schedulingParam The {@link SchedulingParameters}
     * associated with this (and possibly other instances of
     * <code>NoHeapRealtimeThread<code>).
     * @param releaseParam The {@link ReleaseParameters} associated
     * with this (and possibly other instances of <code>NoHeapRealtimeThread</code>).
     * @param memoryArea The {@link MemoryArea} associated with this.
     *
     */
    public NoHeapRealtimeThread(SchedulingParameters schedulingParam,
                                ReleaseParameters releaseParam,
                                MemoryArea memoryArea)
        throws IllegalArgumentException {
        this(schedulingParam,
             releaseParam,
             null,
             memoryArea,
             null,
             null);
    }

    /**
     * Creates a new <code>NoHeapRealtimeThread</code> instance with the
     * given characteristics and a <code>java.lang.Runnable</code>.
     *
     * @param schedulingParam The {@link SchedulingParameters}
     * associated with this (and possibly other instances of
     * <code>NoHeapRealtimeThread<code>).
     * @param releaseParam The {@link ReleaseParameters} associated
     * with this (and possibly other instances of <code>NoHeapRealtimeThread</code>).
     * @param memoryParam The {@link MemoryParameters} associated with
     * this (and possibly other instances of <code>NoHeapRealtimeThread</code>).
     * @param memoryArea The {@link MemoryArea} associated with this.
     * @param groupParam -The {@link ProcessingGroupParameters} associated
     * with this (and possibly other instances of <code>NoHeapRealtimeThread</code>).
     * @param logic the logic for this thread.
     */
    public NoHeapRealtimeThread(SchedulingParameters schedulingParam,
                                ReleaseParameters releaseParam,
                                MemoryParameters memoryParam,
                                MemoryArea memoryArea,
                                ProcessingGroupParameters groupParam,
                                Runnable logic)
        throws IllegalArgumentException {

        super(schedulingParam,
              releaseParam,
              memoryParam,
              memoryArea,
              groupParam,
              logic);

        /* the spec says we throw IllegalArgumentException if
         * memoryArea is null (which *doesn't* happen for regular
         * RealtimeThreads), but doesn't say we throw one if the user passes
         * HeapMemory.instance().  So I guess we defer *that* check until
         * start() is called, then throw a MemoryAccessError. */
        if(memoryArea == null)
            throw new IllegalArgumentException("NoHeapRealtimeThreads cannot be passed a null memory area");

        canTouchHeap = false;
    }

    /**
     * Performs several checks, then starts this {@link
     * NoHeapRealtimeThread} if it is startable.  No parameters or the
     * {@link NoHeapRealtimeThread} object itself may be allocated
     * from the heap.
     *
     * @throws MemoryAccessError if any parameter or <code>this</code>
     * is allocated in the heap, or if this thread was requested to
     * run in the heap.
     */
    public void start() {
        if(heapCheck(this) || heapCheck(releaseParam) ||
           heapCheck(schedulingParam) || heapCheck(memoryParam) ||
           heapCheck(logic) || getActiveMemoryArea() instanceof HeapMemory)
            throw new MemoryAccessError();

        super.start();
    }

    /**
     * Checks if the given object (or any object directly pointed to
     * by it) is in the heap.  Returns true if so.
     *
     * @param o the object to check
     * @return true if the object or any object it directly points to
     * is allocated in the heap
     */
    static native boolean heapCheck(Object o);
}