Class ThreadLocalAction
safepoint
location of the
guest language execution. Thread local actions can be submitted by
languages
or
instruments
. When an action is submitted it will be performed
locally
on the threads they are submitted to. After submitting a thread local action a Future
is
returned that allows to wait for and cancel the submitted action.
Thread local actions can be configured to allow side-effects using the constructor of the action.
If side-effects are allowed (true
), then the thread-local action is allowed to throw
non-internal guest language exceptions from the action and modify the observable guest
application state. Otherwise, the action is not allowed to modify the observable state, and any
non-internal guest language exception will be transformed to an internal error of type
AssertionError
. Side-effects may be temporarily
disabled
by the guest language.
Thread local actions can also be set to be executed in a synchronous or asynchronous way. A
submitted synchronous thread-local action waits until it is started on all threads that it was
submitted on. Then the action is performed
on all
threads. After they were performed on a thread, the action waits for all threads to complete. No
synchronous thread-local actions can be submitted while performing synchronous actions, as this
may lead to deadlocks. If a synchronous event is submitted during a synchronous event, then a
IllegalStateException
is thrown when the action is submitted. Asynchronous thread-local
actions might start and complete to perform independently of each other. There is no restriction
on how they may be submitted.
Thread local actions are guaranteed to be executed in the same order as they were submitted for a context. If a context has pending thread-local actions, the actions may be canceled when the context is canceled or closed invalid. Exceptions thrown by the action will be forwarded handled by the guest language implementation. The only exception is for truffle exceptions that are thrown for non-side-effecting events.
Notifications of blocking:
notifyBlocked(Access)
and notifyUnblocked(Access)
notify thread local actions
that their processing has been blocked/unblocked due to
a blocked call
. notifyBlocked(Access)
is called for each pending action at the
beginning of a blocked call and for each of the continuations of the blocked call after it is
interrupted and thread local actions are processed.
notifyUnblocked(Access)
is called for each pending action at the end of
a blocked call and also right after each of its interruptions, before thread local actions are
processed and the blocked call continues.
In case a thread local action is submitted during a blocked call, the call is interrupted and
notifyUnblocked(Access)
is called without a previous call to
notifyBlocked(Access)
. Recurring thread local actions do not repeatedly interrupt a
blocked call - a blocked call is not interrupted if all pending actions are recurring actions
submitted before the blocked call. New submissions of thread local actions still interrupt
blocked calls, no matter if the new thread local actions are recurring or not. When a blocked
call is interrupted, all pending actions are processed no matter if they are recurring or not.
The notifications of blocking are especially useful for recurring thread local actions as those
actions don't interrupt blocked calls and the notifications inform them about the potentially
long time intervals when those actions are not executed due to the blocked calls. Non-recurring
thread local actions mainly benefit from the notifyUnblocked(Access)
notification telling them that they interrupted a blocked call. For example, a safepoint sampler
might want to exclude the samples from blocked calls.
Example Usage:
Env env; // language or instrument environment env.submitThreadLocal(null, new ThreadLocalAction(true, true) { @Override protected void perform(Access access) { assert access.getThread() == Thread.currentThread(); } @Override protected void notifyBlocked(Access access) { assert access.getThread() == Thread.currentThread(); } @Override protected void notifyUnblocked(Access access) { assert access.getThread() == Thread.currentThread(); } @Override protected String name() { return "MyAction" } });
Further information can be found in the safepoint tutorial.
- Since:
- 21.1
- See Also:
-
Nested Class Summary
Nested Classes -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
ThreadLocalAction
(boolean hasSideEffects, boolean synchronous) Creates a new thread local action.protected
ThreadLocalAction
(boolean hasSideEffects, boolean synchronous, boolean recurring) Creates a new thread local action. -
Method Summary
Modifier and TypeMethodDescriptionprotected void
Callback for notifying the thread local action that its processing has been blocked due toa blocked call
.protected void
Callback for notifying the thread local action that its processing has been unblocked during or while leavinga blocked call
.protected abstract void
perform
(ThreadLocalAction.Access access) Performs the thread local action on a given thread.
-
Constructor Details
-
ThreadLocalAction
protected ThreadLocalAction(boolean hasSideEffects, boolean synchronous) Creates a new thread local action.- Parameters:
hasSideEffects
- true if the event may have side-effects else false.synchronous
- true if the event should run synchronous else the event will run asynchronous.- Since:
- 21.1
- See Also:
-
ThreadLocalAction
protected ThreadLocalAction(boolean hasSideEffects, boolean synchronous, boolean recurring) Creates a new thread local action.- Parameters:
hasSideEffects
- true if the event may have side-effects else false.synchronous
- true if the event should run synchronous else the event will run asynchronous.recurring
- true if the event should be rescheduled until cancelled, else false.- Since:
- 21.1
- See Also:
-
-
Method Details
-
perform
Performs the thread local action on a given thread.- Parameters:
access
- allows access to the current thread and the current code location.- Since:
- 21.1
- See Also:
-
notifyBlocked
Callback for notifying the thread local action that its processing has been blocked due toa blocked call
.- Parameters:
access
- allows access to the current thread and the current code location.- Since:
- 24.2
- See Also:
-
notifyUnblocked
Callback for notifying the thread local action that its processing has been unblocked during or while leavinga blocked call
.- Parameters:
access
- allows access to the current thread and the current code location.- Since:
- 24.2
- See Also:
-