// ************************************************************************
//    $Id: BoundAsyncEventHandler.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 bound asynchronous event handler is an asynchronous event handler
 * that is permanently bound to a thread. Bound asynchronous event
 * handlers are meant for use in situations where the added timeliness
 * is worth the overhead of binding the handler to a thread.
 *
 * @author <a href="mailto:corsaro@cse.wustl.edu">Angelo Corsaro</a>
 * @author <a href="mailto:mdeters@morgandeters.com">Morgan Deters</a>
 * @version 1.0
 */
public class BoundAsyncEventHandler extends AsyncEventHandler {

    /**
     * Creates a new <code>BoundAsyncEventHandler</code> instance whose
     * {@link SchedulingParameters} are inherited from the current thread
     * and does not have either {@link ReleaseParameters} or
     * {@link MemoryParameters}.
     *
     */
    public BoundAsyncEventHandler() {
        this(null, null, null, null, null, false, null);
    }

    /**
     * Creates a new <code>BoundAsyncEventHandler</code> instance with the
     * specified parameters.
     *
     * @param scheduling a {@link SchedulingParameters} value which
     * will be associated with the constructed instance of this.  If
     * <i>null</i> this will be assigned the reference to the {@link
     * SchedulingParameters} of the current thread.
     * @param release a {@link ReleaseParameters} value which will be
     * associated with the constructed instance of this.  If null this
     * will have no {@link ReleaseParameters}.
     * @param memory a {@link MemoryParameters} value which will be
     * associated with the constructed instance of this. If null this
     * will have no {@link MemoryParameters}.
     * @param area The {@link MemoryArea} for this {@link
     * BoundAsyncEventHandler}. If <i>null</i>, inherit the current
     * memory area at the time of construction. The initial memory
     * area must be a reference to a {@link ScopedMemory} or {@link
     * ImmortalMemory} object if <code>nonheap</code> is
     * <code>true</code>.
     * @param group A {@link ProcessingGroupParameters} object to
     * which this will be associated. If <i>null</i> this will not be
     * associated with any processing group.
     * @param nonheap A flag meaning, when <i>true</i>, that
     * this will have characteristics identical to a {@link
     * NoHeapRealtimeThread}. A <i>false</i> value means this will
     * have characteristics identical to a {@link RealtimeThread}. If
     * <i>true</i> and the current thread is not a {@link
     * NoHeapRealtimeThread} or a {@link RealtimeThread} executing
     * within a {@link ScopedMemory} or {@link ImmortalMemory} scope
     * then an {@link IllegalArgumentException} is thrown.
     * @param logic The {@link Runnable} object whose run is executed
     * by {@link AsyncEventHandler#handleAsyncEvent
     * handleAsyncEvent()}.
     * @exception IllegalArgumentException
     */
    public BoundAsyncEventHandler(SchedulingParameters scheduling,
                                  ReleaseParameters release,
                                  MemoryParameters memory,
                                  MemoryArea area,
                                  ProcessingGroupParameters group,
                                  boolean nonheap,
                                  Runnable logic) {
        super(scheduling, release, memory, area, group, nonheap, logic);

        thread = nonheap
            ? new NoHeapRealtimeThread(scheduling,
                                       release,
                                       memory,
                                       area,
                                       group,
                                       handleDispatcher)
            : new RealtimeThread(scheduling,
                                 release,
                                 memory,
                                 area,
                                 group,
                                 handleDispatcher);
        thread.setDaemon(true);
        thread.start();
    }
}