/*
 * @(#) SafeRunnable.java - Interface for safely runnable objects.
 * (c) 2000 Ivan Maidanski <ivmai@chat.ru> http://ivmai.chat.ru
 * Freeware class library sources. All rights reserved.
 **
 * Language: Java [pure]
 * Tested with: JDK v1.1.6
 * Last modified: 2000-12-16 18:50:00 GMT+03:00
 */

/*
 * This software is the proprietary information of the author.
 **
 * Permission to use, copy, and distribute this software and its
 * documentation for non-commercial purposes and without fee is
 * hereby granted provided that this copyright notice appears in all
 * copies.
 **
 * This software should not be modified in any way; any found bug
 * should be reported to the author.
 **
 * The author disclaims all warranties with regard to this software,
 * including all implied warranties of merchantability and fitness.
 * In no event shall the author be liable for any special, indirect
 * or consequential damages or any damages whatsoever resulting from
 * loss of use, data or profits, whether in an action of contract,
 * negligence or other tortuous action, arising out of or in
 * connection with the use or performance of this software.
 */

package ivmai.util;

/**
 * Interface for safely runnable objects.
 **
 * This interface provides the basis safe control over 'active'
 * objects, which start running (single or multiple threads) on the
 * creation and stop when done (or when Java VM terminates or when
 * stop is requested by the user of the object). Active entities may
 * be also interrupted, suspended and resumed safely.
 **
 * @version 2.0
 * @author Ivan Maidanski
 */
public interface SafeRunnable
{

/**
 * Interrupts sleeping or waiting inside active object.
 **
 * Interruption means sending a special <VAR>interrupt</VAR> signal
 * to each thread of active object (resulting in throwing of
 * <CODE>InterruptedException</CODE> inside thread when it is
 * waiting or sleeping). This method returns immediately.
 */
 public abstract void interrupt();

/**
 * Initiates safe suspend operation.
 **
 * This method just sets <VAR>suspending</VAR> flag which signals
 * active object that all its threads (only which are alive) must be
 * safely suspended (turned to sleeping state) as soon as possible.
 * This method returns immediately.
 **
 * @see #waitSuspend()
 * @see #resume()
 * @see #isSuspended()
 * @see #stop()
 */
 public abstract void suspend();

/**
 * Initiates and waits for safe suspend.
 **
 * This method sets <VAR>suspending</VAR> flag which signals active
 * object that all its threads (only which are alive) must be safely
 * suspended (turned to sleeping state) as soon as possible. This
 * method returns just after all threads of active object have been
 * suspended (or died).
 **
 * @see #suspend()
 * @see #resume()
 * @see #isSuspended()
 */
 public abstract void waitSuspend();

/**
 * Resumes running after suspend.
 **
 * This method clears <VAR>suspending</VAR> flag, thus telling
 * active object to resume normal running (stop sleeping) after safe
 * suspend for all its still alive threads. This method returns
 * immediately.
 **
 * @see #suspend()
 * @see #waitSuspend()
 * @see #isSuspended()
 */
 public abstract void resume();

/**
 * Initiates safe stop operation.
 **
 * This method just sets <VAR>stopping</VAR> flag which signals
 * active object that all its threads (only which are alive) must be
 * safely terminated (stopped) as soon as possible. This method
 * returns immediately. If active object is suspended then safe stop
 * operation begins just when resuming.
 **
 * @see #suspend()
 * @see #resume()
 * @see #join()
 * @see #isSuspended()
 * @see #isAlive()
 */
 public abstract void stop();

/**
 * Waits while active object is alive.
 **
 * This method infinitely waits for the death (termination) of all
 * threads inside this active object.
 **
 * @see #stop()
 * @see #isAlive()
 * @see #waitSuspend()
 */
 public abstract void join();

/**
 * Tests whether this active object is suspended.
 **
 * This method just immediately returns <VAR>suspended</VAR> flag
 * which is true only when active object is in safe-suspend state
 * (and alive).
 **
 * @return
 * <CODE>true</CODE> if and only if active object is suspended.
 **
 * @see #suspend()
 * @see #waitSuspend()
 * @see #resume()
 * @see #isAlive()
 */
 public abstract boolean isSuspended();

/**
 * Tests whether this active object is still alive.
 **
 * This method just immediately returns the flag indicating that one
 * or more threads (inside this active object) have not died yet.
 **
 * @return
 * <CODE>true</CODE> if and only if active object is alive.
 **
 * @see #stop()
 * @see #join()
 * @see #isSuspended()
 */
 public abstract boolean isAlive();
}