001: /*
002: * <copyright>
003: *
004: * Copyright 1997-2004 BBNT Solutions, LLC
005: * under sponsorship of the Defense Advanced Research Projects
006: * Agency (DARPA).
007: *
008: * You can redistribute this software and/or modify it under the
009: * terms of the Cougaar Open Source License as published on the
010: * Cougaar Open Source Website (www.cougaar.org).
011: *
012: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
013: * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
014: * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
015: * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
016: * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
017: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
018: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
019: * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
020: * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
021: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
022: * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
023: *
024: * </copyright>
025: */
026:
027: package org.cougaar.core.thread;
028:
029: /**
030: * A Schedulable is an API provided by the {@link
031: * org.cougaar.core.service.ThreadService} that takes the place
032: * of standard Java {@link java.lang.Thread}s and
033: * {@link java.util.TimerTask}s.
034: * <p>
035: * Aside from a few special internal cases, all Threads and Tasks in
036: * Cougaar should come from the ThreadService in the form of
037: * Schedulables. To treat a Schedulable like a Thread, use the start
038: * method. To treat a Schedulable like a TimerTask, use the schedule
039: * methods. The ThreadService is the only source of usable
040: * Schedulables.
041: */
042: public interface Schedulable {
043: /**
044: * Starting a Schedulable is conceptually the same as starting a
045: * Java Thread.
046: * <p>
047: * Note these differences:<ol><li>
048: * The {@link java.lang.Runnable#run()} method invoked due to the
049: * {@link #start()} should return promptly, to free the pooled
050: * Thread for use by other waiting Schedulables.</li><li>
051: * If no thread resources are available, the Schedulable
052: * will be queued instead of running right away. It will only
053: * run when enough resources have become available for it to
054: * reach the head of the queue.</li><li>
055: * If the Schedulable is running at the time of the
056: * call, it will restart itself after the current run finishes
057: * (unless it's cancelled in the meantime). The {@link
058: * java.lang.Runnable#run()} called by {@link #start()} is
059: * single-threaded.</li></ol>
060: */
061: void start();
062:
063: /**
064: * Like {@link #cancel} but with two differences: the Schedulable
065: * can be resumed later, and a special callback is invoked when
066: * the current run finishes.
067: *
068: */
069: void suspend(SuspendCallback callback);
070:
071: /**
072: * Restart after a {@link #suspend).
073: *
074: */
075: void resume();
076:
077: /**
078: * Cancelling a Schedulable will prevent starting if it's
079: * currently queued or from restarting if it was scheduled to do
080: * so. It will not cancel the current run.
081: */
082: boolean cancel();
083:
084: /**
085: * Returns the current state of the Schedulable. The states are
086: * described in {@link CougaarThread}.
087: */
088: int getState();
089:
090: /**
091: * Returns the requestor for whom the ThreadService made this
092: * Schedulable.
093: */
094: Object getConsumer();
095:
096: /**
097: * Lane
098: */
099: int getLane();
100:
101: /**
102: * Other status methods, for the ThreadStatusService
103: */
104:
105: long getTimestamp(); // start time
106:
107: String getName();
108:
109: int getBlockingType();
110:
111: String getBlockingExcuse();
112:
113: /**
114: * The following methods behave more or less as they on
115: * TimerTasks, except that the schedule methods can be called more
116: * than once. In that case, later calls effectively reschedule
117: * the Schedulable. Since 'cancel' was already in use, a new
118: * method had to be introduced to cancel a scheduled task. Thus
119: * 'cancelTimer'.
120: */
121: void schedule(long delay);
122:
123: void schedule(long delay, long interval);
124:
125: void scheduleAtFixedRate(long delay, long interval);
126:
127: void cancelTimer();
128:
129: /**
130: * Notification that a suspend request did its work, ie
131: * the Schedulable is actually suspended.
132: *
133: */
134: interface SuspendCallback {
135: void suspended(Schedulable s);
136: }
137: }
|