public abstract class Realm extends Object
IObservable
must be accessed, and on which these objects will notify their listeners. To
bridge between observables from different realms, subclasses of
Binding
can be used.
A block of code is said to be executing within a realm if calling
isCurrent()
from that block returns true. Code reached by calling
methods from that block will execute within the same realm, with the
exception of methods on this class that can be used to execute code within a
specific realm. Clients can use syncExec(Runnable)
,
asyncExec(Runnable)
, or exec(Runnable)
to execute a
runnable within this realm. Note that using syncExec(Runnable)
can
lead to deadlocks and should be avoided if the current thread holds any
locks.
It is instructive to think about possible implementations of Realm: It can be
based on executing on a designated thread such as a UI thread, or based on
holding a lock. In the former case, calling syncExec on a realm that is not
the current realm will execute the given runnable on a different thread (the
designated thread). In the latter case, calling syncExec may execute the
given runnable on the calling thread, but calling
asyncExec(Runnable)
will execute the given runnable on a different
thread. Therefore, no assumptions can be made about the thread that will
execute arguments to asyncExec(Runnable)
,
syncExec(Runnable)
, or exec(Runnable)
.
It is possible that a block of code is executing within more than one realm.
This can happen for implementations of Realm that are based on holding a lock
but don't use a separate thread to run runnables given to
syncExec(Runnable)
. Realm implementations of this kind should be
appropriately documented because it increases the opportunity for deadlock.
Some implementations of IObservable
provide constructors which do not
take a Realm argument and are specified to create the observable instance
with the current default realm. The default realm can be set for the
currently executing thread by using runWithDefault(Realm, Runnable)
.
Note that the default realm does not have to be the current realm.
Subclasses must override at least one of asyncExec()/syncExec(). For realms based on a designated thread, it may be easier to implement asyncExec and keep the default implementation of syncExec. For realms based on holding a lock, it may be easier to implement syncExec and keep the default implementation of asyncExec.
IObservable
Constructor and Description |
---|
Realm() |
Modifier and Type | Method and Description |
---|---|
void |
asyncExec(Runnable runnable)
Causes the
run() method of the runnable to be invoked from
within this realm at the next reasonable opportunity. |
void |
exec(Runnable runnable)
Causes the
run() method of the runnable to be invoked from
within this realm. |
static Realm |
getDefault()
Returns the default realm for the calling thread, or
null
if no default realm has been set. |
abstract boolean |
isCurrent() |
static void |
runWithDefault(Realm realm,
Runnable runnable)
Sets the provided
realm as the default for the duration of
Runnable.run() and resets the previous realm after completion. |
protected static void |
safeRun(Runnable runnable)
Runs the given runnable.
|
protected static Realm |
setDefault(Realm realm)
Sets the default realm for the calling thread, returning the current
default thread.
|
protected void |
syncExec(Runnable runnable)
Causes the
run() method of the runnable to be invoked from
within this realm at the next reasonable opportunity. |
void |
timerExec(int milliseconds,
Runnable runnable)
Causes the
run() method of the runnable to be invoked from
within this realm after the specified number of milliseconds have
elapsed. |
public static Realm getDefault()
null
if no default realm has been set.null
protected static Realm setDefault(Realm realm)
runWithDefault(Realm, Runnable)
instead. This method is
exposed to subclasses to facilitate testing.realm
- the new default realm, or null
null
public abstract boolean isCurrent()
protected static void safeRun(Runnable runnable)
ISafeRunnable
, the exception is passed to its
handleException method.
runnable
- public void exec(Runnable runnable)
run()
method of the runnable to be invoked from
within this realm. If the caller is executing in this realm, the
runnable's run method is invoked directly, otherwise it is run at the
next reasonable opportunity using asyncExec.
If the given runnable is an instance of ISafeRunnable
, its
exception handler method will be called if any exceptions occur while
running it. Otherwise, the exception will be logged.
runnable
- public void asyncExec(Runnable runnable)
run()
method of the runnable to be invoked from
within this realm at the next reasonable opportunity. The caller of this
method continues to run in parallel, and is not notified when the
runnable has completed.
If the given runnable is an instance of ISafeRunnable
, its
exception handler method will be called if any exceptions occur while
running it. Otherwise, the exception will be logged.
Subclasses should use safeRun(Runnable)
to run the runnable.
runnable
- public void timerExec(int milliseconds, Runnable runnable)
run()
method of the runnable to be invoked from
within this realm after the specified number of milliseconds have
elapsed. If milliseconds is less than zero, the runnable is not executed.
The caller of this method continues to run in parallel, and is not
notified when the runnable has completed.
If the given runnable is an instance of ISafeRunnable
, its
exception handler method will be called if any exceptions occur while
running it. Otherwise, the exception will be logged.
Subclasses should use safeRun(Runnable)
to run the runnable.
milliseconds
- runnable
- protected void syncExec(Runnable runnable)
run()
method of the runnable to be invoked from
within this realm at the next reasonable opportunity. This method is
blocking the caller until the runnable completes.
If the given runnable is an instance of ISafeRunnable
, its
exception handler method will be called if any exceptions occur while
running it. Otherwise, the exception will be logged.
Subclasses should use safeRun(Runnable)
to run the runnable.
Note: This class is not meant to be called by clients and therefore has only protected access.
runnable
- public static void runWithDefault(Realm realm, Runnable runnable)
realm
as the default for the duration of
Runnable.run()
and resets the previous realm after completion.
Note that this will not set the given realm as the current realm.realm
- runnable
-
Copyright (c) 2000, 2014 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.