com.oracle.svm.core.thread

Class VMThreads

java.lang.Object

com.oracle.svm.core.thread.VMThreads

Direct Known Subclasses:

PosixVMThreads, WindowsVMThreads

public abstract class VMThreads
extends Object

Utility methods for the manipulation and iteration of IsolateThreads.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	VMThreads.ActionOnExitSafepointSupport This follows VMThreads.ActionOnTransitionToJavaSupport, but only for exiting safepoint.
static class	VMThreads.ActionOnTransitionToJavaSupport A thread-local enum conveying any actions needed before thread begins executing Java code.
static interface	VMThreads.OSThreadHandle
static interface	VMThreads.OSThreadId
static class	VMThreads.SafepointBehavior
static class	VMThreads.StatusSupport A thread-local enum giving the thread status of a VMThread.

Field Summary

Fields

Modifier and Type	Field and Description
static FastThreadLocalWord<org.graalvm.nativeimage.Isolate>	IsolateTL
static FastThreadLocalWord<org.graalvm.nativeimage.IsolateThread>	nextTL The next element in the linked list of IsolateThreads.
protected static FastThreadLocalWord<VMThreads.OSThreadHandle>	OSThreadHandleTL
static FastThreadLocalWord<org.graalvm.word.UnsignedWord>	StackBase The highest stack address.
static FastThreadLocalWord<org.graalvm.word.UnsignedWord>	StackEnd The lowest stack address.
protected static VMCondition	THREAD_LIST_CONDITION A condition variable for waiting for and notifying on changes to the IsolateThread list.
protected static VMMutex	THREAD_MUTEX Only use this mutex if it is absolutely necessary to operate on the linked list of IsolateThreads.

Constructor Summary

Constructors

Constructor and Description
VMThreads()

Method Summary

Modifier and Type	Method and Description
org.graalvm.nativeimage.IsolateThread	allocateIsolateThread(int isolateThreadSize) Allocate native memory for a IsolateThread.
int	attachThread(org.graalvm.nativeimage.IsolateThread thread) Creates a new IsolateThread and adds it to the list of running threads.
protected void	cleanupExitedOsThreads()
void	detachAllThreadsExceptCurrentWithoutCleanupForTearDown() Detaches all manually attached native threads, but not those threads that were launched from Java, which must be notified to individually exit in the immediately following tear-down.
void	detachThread(org.graalvm.nativeimage.IsolateThread thread) Remove an IsolateThread from the thread list.
static boolean	ensureInitialized() Make sure the runtime is initialized for threading.
abstract void	failFatally(int code, org.graalvm.nativeimage.c.type.CCharPointer message) Report a fatal error to the user and exit.
org.graalvm.nativeimage.IsolateThread	findIsolateThreadForCurrentOSThread(boolean inCrashHandler)
static org.graalvm.nativeimage.IsolateThread	firstThread() Iteration of all IsolateThreads that are currently running.
static org.graalvm.nativeimage.IsolateThread	firstThreadUnsafe() Like VMThreads.firstThread() but without the check that VMThreads.THREAD_MUTEX is locked by the current thread.
void	freeIsolateThread(org.graalvm.nativeimage.IsolateThread thread) Free the native memory allocated by VMThreads.allocateIsolateThread(int).
protected abstract VMThreads.OSThreadHandle	getCurrentOSThreadHandle() Returns a platform-specific handle to the current thread.
protected abstract VMThreads.OSThreadId	getCurrentOSThreadId() Returns a unique identifier for the current thread.
static void	guaranteeOwnsThreadMutex(String message)
protected abstract boolean	initializeOnce() Invoked exactly once early during the startup of an isolate.
static boolean	isInitialized()
static boolean	isTearingDown() Is threading being torn down?
protected abstract void	joinNoTransition(VMThreads.OSThreadHandle osThreadHandle) Executes a non-multithreading-safe low-level (i.e., non-Java-level) join operation on the given native thread.
void	nativeSleep(int milliseconds) Puts this thread to sleep on the operating-system level and does not care about Java semantics.
static org.graalvm.nativeimage.IsolateThread	nextThread(org.graalvm.nativeimage.IsolateThread cur) Iteration of all IsolateThreads that are currently running.
static boolean	ownsThreadMutex()
static boolean	printLocationInfo(Log log, org.graalvm.word.UnsignedWord value, boolean allowUnsafeOperations)
static VMThreads	singleton()
boolean	supportsPatientSafepoints()
void	tearDown()
boolean	verifyIsCurrentThread(org.graalvm.nativeimage.IsolateThread thread)
boolean	verifyThreadIsAttached(org.graalvm.nativeimage.IsolateThread thread)
void	yield()

Methods inherited from class java.lang.Object

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

Field Detail

THREAD_MUTEX

protected static final VMMutex THREAD_MUTEX

Only use this mutex if it is absolutely necessary to operate on the linked list of IsolateThreads. This mutex is especially dangerous because it is used by the application, the GC, and the safepoint mechanism. To avoid potential deadlocks, all places that acquire this mutex must do one of the following:

1. Acquire the mutex within a VM operation: this is safe because it fixes the order in which the mutexes are acquired (VMOperation queue mutex first, VMThreads.THREAD_MUTEX second). If the VM operation causes a safepoint, then it is possible that the VMThreads.THREAD_MUTEX was already acquired for safepoint reasons.
2. Acquire the mutex from a thread that is either not yet attached VMThreads.StatusSupport.STATUS_CREATED or currently in native code (VMThreads.StatusSupport.STATUS_IN_NATIVE).

Deadlock example 1:

• Thread A acquires the VMThreads.THREAD_MUTEX.
• Thread B queues a VM operation and therefore holds the corresponding VM operation queue mutex.
• Thread A allocates an object and the allocation wants to trigger a GC. So, a VM operation needs to be queued, and thread A tries to acquire the VM operation queue mutex. Thread A is blocked because thread B holds that mutex.
• Thread B needs to initiate a safepoint before executing the VM operation. So, it tries to acquire the VMThreads.THREAD_MUTEX and is blocked because thread A holds that mutex.

Deadlock example 2:

• Thread A acquires the VMThreads.THREAD_MUTEX.
• Thread A allocates an object and the allocation wants to trigger a GC. So, a VM operation is queued and thread A blocks until the VM operation is completed.
• The dedicated VM operation thread needs to initiate a safepoint for the execution of the VM operation. So, it tries to acquire VMThreads.THREAD_MUTEX and is blocked because thread A still holds that mutex.

THREAD_LIST_CONDITION

protected static final VMCondition THREAD_LIST_CONDITION

A condition variable for waiting for and notifying on changes to the IsolateThread list.

nextTL

public static final FastThreadLocalWord<org.graalvm.nativeimage.IsolateThread> nextTL

The next element in the linked list of IsolateThreads. A thread points to itself with this field after being removed from the linked list.

OSThreadHandleTL

protected static final FastThreadLocalWord<VMThreads.OSThreadHandle> OSThreadHandleTL

IsolateTL

public static final FastThreadLocalWord<org.graalvm.nativeimage.Isolate> IsolateTL

StackBase

public static final FastThreadLocalWord<org.graalvm.word.UnsignedWord> StackBase

The highest stack address.

StackEnd

public static final FastThreadLocalWord<org.graalvm.word.UnsignedWord> StackEnd

The lowest stack address. Note that this value does not necessarily match the value that is used for the stack overflow check.

Constructor Detail

VMThreads

public VMThreads()

Method Detail

singleton

public static VMThreads singleton()

isInitialized

public static boolean isInitialized()

isTearingDown

public static boolean isTearingDown()

Is threading being torn down?

ensureInitialized

public static boolean ensureInitialized()

Make sure the runtime is initialized for threading.

initializeOnce

protected abstract boolean initializeOnce()

Invoked exactly once early during the startup of an isolate. Subclasses can perform initialization of native OS resources.

allocateIsolateThread

public org.graalvm.nativeimage.IsolateThread allocateIsolateThread(int isolateThreadSize)

Allocate native memory for a IsolateThread. The returned memory must be initialized to 0.

freeIsolateThread

public void freeIsolateThread(org.graalvm.nativeimage.IsolateThread thread)

Free the native memory allocated by VMThreads.allocateIsolateThread(int).

failFatally

public abstract void failFatally(int code,
                                 org.graalvm.nativeimage.c.type.CCharPointer message)

Report a fatal error to the user and exit. This method must not return.

firstThread

public static org.graalvm.nativeimage.IsolateThread firstThread()

Iteration of all IsolateThreads that are currently running. VMThreads.THREAD_MUTEX must be held when iterating the list. Use the following pattern to iterate all running threads. It is allocation free and can therefore be used during GC:

 for (VMThread thread = VMThreads.firstThread(); thread.isNonNull(); thread = VMThreads.nextThread(thread)) {
 

firstThreadUnsafe

public static org.graalvm.nativeimage.IsolateThread firstThreadUnsafe()

Like VMThreads.firstThread() but without the check that VMThreads.THREAD_MUTEX is locked by the current thread. Only use this method if absolutely necessary (e.g., for printing diagnostics on a fatal error).

nextThread

public static org.graalvm.nativeimage.IsolateThread nextThread(org.graalvm.nativeimage.IsolateThread cur)

Iteration of all IsolateThreads that are currently running. See VMThreads.firstThread() for details.

attachThread

public int attachThread(org.graalvm.nativeimage.IsolateThread thread)

Creates a new IsolateThread and adds it to the list of running threads. This method must be the first method called in every thread.

detachThread

public void detachThread(org.graalvm.nativeimage.IsolateThread thread)

Remove an IsolateThread from the thread list. This method must be the last method called in every thread.

cleanupExitedOsThreads

protected void cleanupExitedOsThreads()

tearDown

public void tearDown()

detachAllThreadsExceptCurrentWithoutCleanupForTearDown

public void detachAllThreadsExceptCurrentWithoutCleanupForTearDown()

Detaches all manually attached native threads, but not those threads that were launched from Java, which must be notified to individually exit in the immediately following tear-down. We cannot clean up the threads we detach here because cleanup code needs to run in the detaching thread itself. We assume that this is tolerable considering the immediately following tear-down.

joinNoTransition

protected abstract void joinNoTransition(VMThreads.OSThreadHandle osThreadHandle)

Executes a non-multithreading-safe low-level (i.e., non-Java-level) join operation on the given native thread. If the thread hasn't yet exited on the operating system level, this method blocks until the thread exits on the operating system level. After successfully joining a thread, the operating system may free resources and recycle/reuse the given thread id for other newly started threads. As this method is marked as uninterruptible, it may only be used for joining threads that were already detached from SVM. Otherwise, this could result in deadlocks.

getCurrentOSThreadHandle

protected abstract VMThreads.OSThreadHandle getCurrentOSThreadHandle()

Returns a platform-specific handle to the current thread. This handle can for example be used for joining a thread. Depending on the specific platform, it can be necessary to explicitly free the handle when it is no longer used. To avoid leaking operating system resources, this method should therefore only be called in VMThreads.attachThread(IsolateThread), when VMThreads.OSThreadHandleTL is not set yet.

getCurrentOSThreadId

protected abstract VMThreads.OSThreadId getCurrentOSThreadId()

Returns a unique identifier for the current thread.

nativeSleep

public void nativeSleep(int milliseconds)

Puts this thread to sleep on the operating-system level and does not care about Java semantics. May only be used in very specific situations, e.g., when printing diagnostics.

yield

public void yield()

supportsPatientSafepoints

public boolean supportsPatientSafepoints()

verifyThreadIsAttached

public boolean verifyThreadIsAttached(org.graalvm.nativeimage.IsolateThread thread)

verifyIsCurrentThread

public boolean verifyIsCurrentThread(org.graalvm.nativeimage.IsolateThread thread)

findIsolateThreadForCurrentOSThread

public org.graalvm.nativeimage.IsolateThread findIsolateThreadForCurrentOSThread(boolean inCrashHandler)

guaranteeOwnsThreadMutex

public static void guaranteeOwnsThreadMutex(String message)

ownsThreadMutex

public static boolean ownsThreadMutex()

printLocationInfo

public static boolean printLocationInfo(Log log,
                                        org.graalvm.word.UnsignedWord value,
                                        boolean allowUnsafeOperations)