ewe.sys
Class Coroutine

java.lang.Object
  ewe.sys.Coroutine

All Implemented Interfaces:

Runnable

public final class Coroutine

extends Object

implements Runnable

A Coroutine is a non-preemptive implementation of a multi-threading. Only one Coroutine will ever by running at a time and control is only passed to other Coroutines when Coroutine.sleep(int millis) is called.

Ewe is single-threaded and only one callback or coroutine thread is ever running at one time (although the Vm itself may have multiple threads servicing these various functions). However callback threads are NOT Coroutine threads.

Avoid creating Coroutines directly - instead use the ewe.sys.mThread object instead. This object has a very similar API to a standard Java Thread and uses a Coroutine as its "engine" when started.

You have to explicitly create Coroutine threads yourself by calling the constructor and passing it a Runnable object.

Field Summary

protected int	context
protected Runnable	runnable
boolean	showExceptionTrace If this is true then any uncaught throwable/exception that causes the Coroutine to exit will be displayed.

Constructor Summary

Coroutine(Object target, Method runMethod, Object targetData)
Deprecated. use an mThread object instead.

Coroutine(Object target, String methodName, Object targetData)
Deprecated. use an mThread object instead.

Coroutine(Runnable r)
Deprecated. use an mThread object instead.

Coroutine(Runnable r, int stackSize)
Deprecated. - use an mThread object instead.

Method Summary

protected void	_nativeCreate(int stackSize)
static int	count() This returns a count of all running Coroutines.
static Coroutine	getCurrent() Find the Coroutine which is running the current thread.
void	interrupt() Interrupts the Coroutine if it was in a sleep() or a join().
boolean	isRunning() Returns whether the Coroutine is still running.
static int	join(Coroutine other, int millis) Tells the current Coroutine thread to sleep until the other Coroutine thread has exited.
static int	nap(int iterations, int time) This calls sleep(time) every "iterations" calls of this method.
void	run() This will actually not get called!
static int	sleep(int howLong) Puts the current Coroutine thread to sleep, thereby allowing other coroutines as well as message/timer/callback threads to run.
void	wakeup() Deprecated. - use interrupt() instead, interrupt() will interrupt join() calls.
static void	yield()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, toString

Field Detail

context

protected int context

runnable

protected Runnable runnable

showExceptionTrace

public boolean showExceptionTrace

If this is true then any uncaught throwable/exception that causes the Coroutine to exit will be displayed. By default it is false.

Constructor Detail

Coroutine

public Coroutine(Runnable r,
                 int stackSize)

Deprecated. - use an mThread object instead.

Coroutine

public Coroutine(Runnable r)

Deprecated. use an mThread object instead.

Coroutine

public Coroutine(Object target,
                 Method runMethod,
                 Object targetData)

Deprecated. use an mThread object instead.

Coroutine

public Coroutine(Object target,
                 String methodName,
                 Object targetData)

Deprecated. use an mThread object instead.

Method Detail

run

public final void run()

This will actually not get called!

Specified by:

run in interface Runnable

_nativeCreate

protected final void _nativeCreate(int stackSize)

isRunning

public final boolean isRunning()

Returns whether the Coroutine is still running. i.e. the run() method of the runnable object assigned to the Coroutine has not yet exited.

getCurrent

public static final Coroutine getCurrent()

Find the Coroutine which is running the current thread. If this thread is not being run by a Coroutine, it will return null.

yield

public static final void yield()

sleep

public static final int sleep(int howLong)

Puts the current Coroutine thread to sleep, thereby allowing other coroutines as well as message/timer/callback threads to run. This method is made static as it can ONLY be run correctly from a running Coroutine ON that same Coroutine. This method may NOT be called by a Coroutine from within a native method - or from within a method which has a native method in the call chain.

Parameters:

howLong - - The length of time in milliseconds to sleep. If howLong == -1 it will sleep until interrupt() is envoked on it.

Returns:

1 if it slept() and then woke up after the timeout time, or 0 if it was woken by wakeup() or -1 if it was interrupted.

join

public static final int join(Coroutine other,
                             int millis)

Tells the current Coroutine thread to sleep until the other Coroutine thread has exited. It returns true if the other had exited or false if it had not. If timeout is -1 then it will wait forever. This waiting will NOT be affected by wakeup(), but will be by interrupt();

Parameters:

other - The other Coroutine to wait for.

Returns:

1 if the other Coroutine exited.
0 if the a timeout occured before the other Coroutine exited.
-1 if an interrupt() was called on this Coroutine.

wakeup

public final void wakeup()

Deprecated. - use interrupt() instead, interrupt() will interrupt join() calls.

Tells the Coroutine to stop sleeping if it was in a sleep(). Otherwise, if it were in join() or it had exited it will have no effect.

interrupt

public final void interrupt()

Interrupts the Coroutine if it was in a sleep() or a join(). Otherwise, if it were had exited it will have no effect.

count

public static final int count()

This returns a count of all running Coroutines. Coroutines which are not running are not counted and will eventually be garbage collected.

nap

public static final int nap(int iterations,
                            int time)

This calls sleep(time) every "iterations" calls of this method.