org.erights.e.elib.vat
Class Runner

java.lang.Object
  |
  +--org.erights.e.elib.vat.Runner

Direct Known Subclasses:

AWTRunner, DeadRunner, HeadlessRunner, SWTRunner

public abstract class Runner

extends Object

Untamed:

Field Summary

private FlexList	myEStack A stack of EStackItems used for causality tracing.
(package private) Vat	myOptServingVat To be set by PendingEvent to the Vat that enqueued the event currently being served, or null if idle.
(package private) long	myServingTicket To be set by PendingEvent to the ticket taken from myOptServingVat by the event currently being served at the time that event was enqueued, or -1 if idle.

Constructor Summary

(package private)

Runner()

Method Summary

(package private) abstract void	addDeadManSwitch(Object deadManSwitch) Remember the deadManSwitch, so that if I'm shut down, I can notify him.
(package private) abstract void	disturbEvent(Throwable t) Deprecated. Since Thread.stop(Throwable) is also deprecated, but will be available as long as Thread.stop(Throwable) remains available.
(package private) abstract Throwable	enqueue(PendingEvent todo) Add todo to the queue my thread is servicing
(package private) static Runner	getCurrentRunner() If called from within a thread servicing a Runner, returns that Runner; otherwise it's an external thread and we throw an exception.
(package private) static Runner	getOptCurrentRunner() If called from within a thread servicing a Runner, returns that Runner; otherwise it's an external thread and we return null.
(package private) static ConstList	getOptEStack() Returns a list of EStackItems
(package private) Vat	getOptServingVat() The Vat that queued the event now being run(), or null if idle.
(package private) abstract String	getRunnerKind() What kind of Runner is this?
(package private) abstract boolean	isCurrent() Is the current thread this Runner's thread (the thread servicing this Vat)?
(package private) static Runner	obtainRunner(String runnerKind) optName defaults to null
(package private) static Runner	obtainRunner(String runnerKind, String optName) Gets or makes a Runner of the specified kind.
static void	popEStackItem() Enabled: XXX Should be suppressed by taming.
static void	pushEStackItem(EStackItem item) Enabled: XXX Should be suppressed by taming.
(package private) void	requireCurrent() If not isCurrent(), throw an exception
(package private) long	servingTicket() The ticket number of the event currently being run(), or -1 if idle.
(package private) abstract void	setPriority(int newPriority) Requests a change of priority of the thread servicing this Runner.
(package private) Runner	shorten() If x.shorten() != x, then this Runner is no more, and should not be used.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

myOptServingVat

Vat myOptServingVat

To be set by PendingEvent to the Vat that enqueued the event currently being served, or null if idle.

myServingTicket

long myServingTicket

To be set by PendingEvent to the ticket taken from myOptServingVat by the event currently being served at the time that event was enqueued, or -1 if idle.

myEStack

private final FlexList myEStack

A stack of EStackItems used for causality tracing.

Constructor Detail

Runner

Runner()

Method Detail

getOptCurrentRunner

static Runner getOptCurrentRunner()

If called from within a thread servicing a Runner, returns that Runner; otherwise it's an external thread and we return null.

There are two kinds of threads which we take to be servicing a Runner.

• A RunnerThread created to service a Runner, currently used for the "headless" and "swt" runnerKinds.
• A pre-existing thread servicing a pre-existing event-queue mechanism, managing some device or system of devices that one might want to synchronously access from E, or (via callbacks) have synchronous access to E. This is currently used for the "awt" runnerKind.

Let's call a thread not servicing a Runner an external thread, since it is external in some sense to E. (E-language code and normal ELib code should never execute in an external thread.) getOptCurrentRunner() == null iff it's invoked from an external thread.

getCurrentRunner

static Runner getCurrentRunner()

If called from within a thread servicing a Runner, returns that Runner; otherwise it's an external thread and we throw an exception.

obtainRunner

static Runner obtainRunner(String runnerKind)

optName defaults to null

See Also:

obtainRunner(String, String)

obtainRunner

static Runner obtainRunner(String runnerKind,
                           String optName)

Gets or makes a Runner of the specified kind.

Parameters:

runnerKind - says which kind of Runner to make.

optName - If we are making a new Runner, the name is used to tag it and its thread for debugging purposes.

pushEStackItem

public static void pushEStackItem(EStackItem item)

Enabled: XXX Should be suppressed by taming.

popEStackItem

public static void popEStackItem()

Enabled: XXX Should be suppressed by taming.

getOptEStack

static ConstList getOptEStack()

Returns a list of EStackItems

shorten

Runner shorten()

If x.shorten() != x, then this Runner is no more, and should not be used. This can happen only to HeadlessRunners.

Returns:

The end of the merge chain. The default implementation here in Runner just returns this.

enqueue

abstract Throwable enqueue(PendingEvent todo)

Add todo to the queue my thread is servicing

setPriority

abstract void setPriority(int newPriority)

Requests a change of priority of the thread servicing this Runner.

disturbEvent

abstract void disturbEvent(Throwable t)

Deprecated. Since Thread.stop(Throwable) is also deprecated, but will be available as long as Thread.stop(Throwable) remains available.

Performs a Thread.stop(t) on the thread executing the current event.

Note that Thread.stop() does not stop the thread (obvious huh?), but rather causes that thread to experience a "spontaneously" thrown exception.

getOptServingVat

Vat getOptServingVat()

The Vat that queued the event now being run(), or null if idle.

Used for causality tracing.

See Also:

servingTicket()

servingTicket

long servingTicket()

The ticket number of the event currently being run(), or -1 if idle.

Used for causality tracing. The serving ticket count was dispensed by one of my enqueueing Vats and can only be understood relative to that Vat. Use getOptServingVat() to get that Vat.

getRunnerKind

abstract String getRunnerKind()

What kind of Runner is this?

A kind of Runner determines which kind of "devices" (eg, AWT or SWT widgets) may be synchronously accessed from within this Runner

Returns:

one of "awt", "swt", "dead", or "headless". If "headless", this makes an HeadlessRunner, which may later be redirected, so use with caution. This list may be extended over time.

isCurrent

abstract boolean isCurrent()

Is the current thread this Runner's thread (the thread servicing this Vat)?

If it is, we say we are executing inside this Runner.

r.isCurrent() implies getCurrentRunner() == r.

requireCurrent

void requireCurrent()

If not isCurrent(), throw an exception

addDeadManSwitch

abstract void addDeadManSwitch(Object deadManSwitch)

Remember the deadManSwitch, so that if I'm shut down, I can notify him.

The deadManSwitch is only notified if it's be a boot-ref (a Ref handled by a BootRefHandler whose target's vat is a vat handled by a different Runner. Otherwise, the notification would need to occur in this Runner, which is presumably already shut down.