Home:	Java Fair Threads
Previous chapter:	Fair Thread Framework
Next chapter:	Examples

The interface Event basically defines two methods: one for hashcoding events, and one for comparing them; these two methods are the minimum needed for implementing events.

public interface Event
{
   boolean equals(Object object);
   public int hashCode();
}

public class StringEvent implements Event
{
    public String identity;
    public StringEvent(String s){ identity = s; }
    public int hashCode(){ return identity.hashCode(); }
    public boolean equals(Object object){
       if (object instanceof StringEvent) 
           return identity.equals(((StringEvent)object).identity);
       return false;
    }
}

The interface of fair threads is the following:

public interface FairThreadInterface
{
   void run(FairScheduler scheduler);   
   void start(FairScheduler scheduler);
   void stop(FairScheduler scheduler);
   void suspend(FairScheduler scheduler);
   void resume(FairScheduler scheduler);
  
   void cooperate();
   void cooperate(long delay);
  
   void join(FairThread thread);
   void join(FairThread thread,long delay);
   
   void generate(Event event);
   void generate(String event);
   void generate(Event event,Object val);
   void generate(String event,Object val);

   void await(Event event);
   void await(String event);
   void await(Event event,long delay);
   void await(String event,long delay);

   final static public Object NULL = new Object();
   Object nextValue(Event event);
   Object nextValue(String event);  
}

Control over Threads

• Method run(FairScheduler s) is the basic method executed by the fair thread; s is the fair scheduler that runs the thread. By default, the method does nothing. This method corresponds to the run() method of standard Java threads.
• Method start(FairScheduler s) starts execution of the fair thread by s. It corresponds to the start() method of standard threads.
• Method stop(FairScheduler s) stops the fair thread run by s. It corresponds to the stop() method of Java version 1, which is now deprecated.
• Method suspend(FairScheduler s) is used to suspend the fair thread run by s; execution can be resumed by calling the resume(FairScheduler) method. It corresponds to the suspend() method of Java version 1 which is now deprecated.
• Method resume(FairScheduler s) resumes the thread, previously suspended by a call to suspend(FairScheduler). It corresponds to the suspend() method of Java version 1 which is now deprecated.

Cooperation

• Method cooperate() is the method to be called by the fair thread to cooperate with other threads; it is the basic mechanism of FairThreads. It corresponds to yield() of standard threads.
• By calling method cooperate(long n) the fair thread falls asleep during n phases. The method corresponds to the sleep(long) method of standard threads. Actually, cooperate(n) is a loop that runs cooperate() n times.

Joining Threads

• Method join(FairThread t) waits for the termination of the fair thread t. It corresponds to method join() of standard threads.
• Method join(FairThread t,long n) waits for termination of the fair thread t during at most n phases. It corresponds to the method join(long) of standard threads.

Generation of Events

Awaiting Events

• Method await(Event e) waits for e. It corresponds to the function called pthread_cond_wait of Pthreads. Method await(String s) is similar, s being converted to an event.
• Method await(Event e,long n) waits for event e during at most n phases. It corresponds to the function called pthread_cond_timedwait of Pthreads. Method await(String s,long n) is similar, s being converted to an event.

Generated Values

• Method nextValue(Event e) returns the next value of e generated during the current phase. Value NULL is returned if the value generated was null. Value null is returned if no new generated value is available. In this last case, nextValue remains blocked up to the end of the current phase, and returns during the next phase (indeed, absence of a value is impossible to decide before the end of the current phase, as otherwise it could be produced by a thread scheduled later in the same phase). Method nextValue(String s) is similar, s being converted to an event.

Interface of fair schedulers is the following:

public interface FairSchedulerInterface
{   
   void broadcast(Event event);
   void broadcast(String event);
   void broadcast(Event event,Object val);
   void broadcast(String event,Object val);

   void start(FairThread thread);
   void stop(FairThread thread);
   void suspend(FairThread thread);
   void resume(FairThread thread);
}

• Method broadcast(Event e) broadcasts e to all executing fair threads. Method broadcast(String s) is similar, s being converted to an event. Method broadcast(Event e, Object o) broadcasts e, with o as generated value. Method broadcast(String s,Object o) is similar, s being converted to an event.
• Method start(FairThread t) starts t. The call scheduler.start(thread) is equivalent to thread.start(scheduler).
• Method stop(FairThread t) stops t. The call scheduler.stop(thread) is equivalent to thread.stop(scheduler).
• Method suspend(FairThread t) suspends t. The call scheduler.suspend (thread) is equivalent to the call thread.suspend(scheduler).
• Method resume(FairThread t) resumes thread t. The call scheduler.resume (thread) is equivalent to thread.resume(scheduler).

Fair threads are instance of the FairThread class which extends the standard class Thread. Class FairThread implements interface FairThreadInterface and has two constructors:

public FairThread()
public FairThread(Fair fair)

• The first constructor is used to create a fair thread with the default empty run (FairScheduler) method. It corresponds to the constructor without parameter of the class Thread.
• The second constructor creates a fair thread from a fair object (see section \ref{Fair Interface}) given as argument. It corresponds to the constructor with a Runnable parameter of the class Thread.

Fair schedulers are instances of the class FairScheduler which has one single constructor:

public FairScheduler()

Interface Fair is to be implemented by objects given to the fair thread constructor. It corresponds to the Runnable interface of standard Java threads.

public interface Fair
{
   void run(FairScheduler scheduler,FairThread thread); 
}

• The run(FairScheduler s,FairThread t) method is the basic method executed by fair thread t, run by the fair scheduler s.

A fair process corresponds to a standard process created by the call exec(String) of the class Runtime, with the difference that it can be safely immerged in the FairThreads framework. Fair processes are instances of the class FairProcess which extends FairThread; it has one single constructor:

FairProcess(String command)