Class Realm
- java.lang.Object
-
- org.eclipse.core.databinding.observable.Realm
-
- Direct Known Subclasses:
DisplayRealm
public abstract class Realm extends Object
A realm defines a context from which objects implementingIObservable
must be accessed, and on which these objects will notify their listeners. To bridge between observables from different realms, subclasses ofBinding
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 usesyncExec(Runnable)
,asyncExec(Runnable)
, orexec(Runnable)
to execute a runnable within this realm. Note that usingsyncExec(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 toasyncExec(Runnable)
,syncExec(Runnable)
, orexec(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 usingrunWithDefault(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.
- Since:
- 1.0
- See Also:
IObservable
-
-
Constructor Summary
Constructors Constructor Description Realm()
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description void
asyncExec(Runnable runnable)
Causes therun()
method of the runnable to be invoked from within this realm at the next reasonable opportunity.void
exec(Runnable runnable)
Causes therun()
method of the runnable to be invoked from within this realm.static Realm
getDefault()
Returns the default realm for the calling thread, ornull
if no default realm has been set.abstract boolean
isCurrent()
static void
runWithDefault(Realm realm, Runnable runnable)
Sets the providedrealm
as the default for the duration ofRunnable.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 therun()
method of the runnable to be invoked from within this realm at the next reasonable opportunity.void
timerExec(int milliseconds, Runnable runnable)
Causes therun()
method of the runnable to be invoked from within this realm after the specified number of milliseconds have elapsed.
-
-
-
Method Detail
-
getDefault
public static Realm getDefault()
Returns the default realm for the calling thread, ornull
if no default realm has been set.- Returns:
- the default realm, or
null
-
setDefault
protected static Realm setDefault(Realm realm)
Sets the default realm for the calling thread, returning the current default thread. This method is inherently unsafe, it is recommended to userunWithDefault(Realm, Runnable)
instead. This method is exposed to subclasses to facilitate testing.- Parameters:
realm
- the new default realm, ornull
- Returns:
- the previous default realm, or
null
-
isCurrent
public abstract boolean isCurrent()
- Returns:
- true if the caller is executing in this realm. This method must not have side-effects (such as, for example, implicitly placing the caller in this realm).
-
safeRun
protected static void safeRun(Runnable runnable)
Runs the given runnable. If an exception occurs within the runnable, it is logged and not re-thrown. If the runnable implementsISafeRunnable
, the exception is passed to itshandleException
method.- Parameters:
runnable
-Runnable
to execute
-
exec
public void exec(Runnable runnable)
Causes therun()
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.- Parameters:
runnable
-Runnable
to execute
-
asyncExec
public void asyncExec(Runnable runnable)
Causes therun()
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.- Parameters:
runnable
-Runnable
to execute
-
timerExec
public void timerExec(int milliseconds, Runnable runnable)
Causes therun()
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.- Parameters:
milliseconds
- wait time before executing the runnablerunnable
-Runnable
to execute- Since:
- 1.2
-
syncExec
protected void syncExec(Runnable runnable)
Causes therun()
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.
- Parameters:
runnable
-Runnable
to execute
-
runWithDefault
public static void runWithDefault(Realm realm, Runnable runnable)
Sets the providedrealm
as the default for the duration ofRunnable.run()
and resets the previous realm after completion. Note that this will not set the given realm as the current realm.- Parameters:
realm
- default realm for the runnablerunnable
-Runnable
to execute
-
-