hythread_ext.h File Reference

Detailed Description

Extended Treading and synchronization support.

Thread Manager native interface. Provides basic capablitites for managing native threads in the system.

Overview

The Thread Manager (TM) component provides various threading functionality for VM and class libraries code. provides support for threading inside the virtual machine and for class libraries. The implementation of thread management uses the black-box approach exposing two interfaces: Java and native. The whole component is divided into two layers: the middle layer of native threading with the layer of Java threading on top. The implementation of Thread manager is based solely on the Apache Portable Runtime (APR) layer.

The top layer provides the following functionality (see jthread, thread_ti.h):

Maps Java threads onto OS native threads
Support kernel classes support
Support JVMTI

The middle layer does the following (see hythread.h, hythread_ext.h):

Provides API for native threading
Wrapping 223shield224 on top of porting layer
Provides support for safe suspension and interrupt
Additional functionality that missed in porting layer

Interaction

The following components are primary customers of the Thread Manager:

Kernel classes
Garbage collector
java.util.concurrent classes
java.lang.management classes
JVMTI

These components interact with different parts of thread management: some work with Java threads and objects, while others interact with the middle layer of native threading. Whenever the component operates with Java objects and threads, it would call the top (Java) interface functions. Otherwise, it would call the middle (native) interface functions.

Safe suspension

One of the key features of thread management in the VM is the safe suspension functionality. The purpose of the safe suspension mechanism is mostly to ensure that:

Suspended thread can be safely explored by the Garbage Collector while enumerating live references;
Suspended thread is guaranteed to do not hold any system-critical locks which can be requested by the other parts of VM, such as the locks associated with the native memory heap.

At every time moment, thread can be in one of three possible states:

Safe region. A period of time during thread execution when the thread can be safely suspended. This would typically be a region of a native C code where java objects and stack are not changed. An example is native file I/O call which reads a big amount of data from disk.
Unsafe region. A period of time during thread execution when the code is in process of changing java objects or impacts java stack, such as parts of the JITT-ed java code or JNI function calls. Suspending a thread in that region would typically be unsafe.
Safe point. A single point during the thread execution time when the thread can safely suspended. For example, JIT may want to injec t the safe points in the Java code between the selected chunks of the assembly code, those size is determined in terms of performance balanc e between safe point function call overhead and suspension time overhead.

Each thread managed by TM has the following fields:

safe_region 226 boolean flag which reports whether suspend is safe at this moment or not.
request 226 integer indicating if any request for suspension were made for this thread
suspend_count 226 integer indicating how many requests for suspension were made for this thread
safe_region_event 226 event indicating that thread has reached safe region
resume_event 226 event indicating that thread needs to be awakened

The suspension algorithm typically invokes two threads 226 223suspender224 thread and 223suspendee224 thread. A typical example is than "suspender" is GC thread, and the "suspendee" is Java thread. The safe thread suspension algorithm works as follows:

1. GC thread invokes thread_supend() method of a thread manager which does the following:
a. If Java thread was already requested to suspend, increase the suspend_count count and return;
b. Increase suspend_count for Java thread;
c. If Java thread is currently in unsafe region, wait while it reaches the safe region.
2. GC thread, after completing the enumeration-related activities, calls the resume_thread() method which does the following:
a. If suspend_count was previously set, decrease the number of suspend requests;
b. If the number of suspend requests reaches zero, notifies the Java thread that it can wake up now.
3. A Java thread may reach safe point, which is denoted by calling the safe_point() method in the Java thread.
The safe_point() method does the following:
a. If there was request for suspension then:
i. notify GC thread that it can proceed with enumeration activities
ii. wait for the resume notification to come from the GC thread
4. A Java thread may enter the safe region, which is denoted by calling the suspend_enable() method in the Java thread.
The suspend_enable() method does the following:
a. Sets the flag safe_region to true;
b. If there was a request for suspension, notifies the GC thread that Java thread has reached safe region so GC may
proceed with enumeration activities
5. A Java thread may leave the safe region, which is denoted by calling the suspend_disable() method in the Java thread.
The suspend_disable() method does the following:
a. Sets the flag safe_region to false;
b. Calls the safe_point() method.

For more detailes see thread manager component documentation located at vm/thread/doc/ThreadManager.htm

Classes

struct HyThread

Native thread control structure. More...

struct hythread_start_proc_data

Start procedure data structure. More...

struct tm_props

#define LOCK_RESERVATION

Opaque structures.

typedef HyLatch * hylatch_t

Opaque structures.

typedef HyThread * hythread_iterator_t

Opaque structures.

typedef HyThreadLibrary * hythread_library_t

Opaque structures.

typedef U_32 hythread_thin_monitor_t

Opaque structures.

typedef void(*) hythread_event_callback_proc (void)

Opaque structures.

typedef int(HYTHREAD_PROC *) hythread_wrapper_t (void *)

Opaque structures.

typedef hythread_start_proc_data * hythread_start_proc_data_t

Opaque structures.

VMIMPORT tm_props * tm_properties

Opaque structures.

State query

#define TM_THREAD_QUANTITY_OF_PREDEFINED_TLS_KEYS   1

int VMCALL hythread_is_alive (hythread_t thread)

int VMCALL hythread_is_terminated (hythread_t thread)

int VMCALL hythread_is_runnable (hythread_t thread)

int VMCALL hythread_is_blocked_on_monitor_enter (hythread_t thread)

int VMCALL hythread_is_waiting (hythread_t thread)

int VMCALL hythread_is_waiting_indefinitely (hythread_t thread)

int VMCALL hythread_is_waiting_with_timeout (hythread_t thread)

int VMCALL hythread_is_sleeping (hythread_t thread)

int VMCALL hythread_is_in_monitor_wait (hythread_t thread)

int VMCALL hythread_is_parked (hythread_t thread)

int VMCALL hythread_is_suspended (hythread_t thread)

int VMCALL hythread_is_interrupted (hythread_t thread)

int VMCALL hythread_is_in_native (hythread_t thread)

int VMCALL hythread_is_daemon (hythread_t thread)

Defines

#define HYTHREAD_EXT_H

#define TM_THREAD_STATE_NEW   0

TM Thread states constants.

#define TM_THREAD_STATE_ALIVE   JVMTI_THREAD_STATE_ALIVE

TM Thread states constants.

#define TM_THREAD_STATE_TERMINATED   JVMTI_THREAD_STATE_TERMINATED

TM Thread states constants.

#define TM_THREAD_STATE_WAITING   JVMTI_THREAD_STATE_WAITING

TM Thread states constants.

#define TM_THREAD_STATE_WAITING_INDEFINITELY   JVMTI_THREAD_STATE_WAITING_INDEFINITELY

TM Thread states constants.

#define TM_THREAD_STATE_WAITING_WITH_TIMEOUT   JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT

TM Thread states constants.

#define TM_THREAD_STATE_RUNNABLE   JVMTI_THREAD_STATE_RUNNABLE

TM Thread states constants.

#define TM_THREAD_STATE_SLEEPING   JVMTI_THREAD_STATE_SLEEPING

TM Thread states constants.

#define TM_THREAD_STATE_IN_MONITOR_WAIT   JVMTI_THREAD_STATE_IN_OBJECT_WAIT

TM Thread states constants.

#define TM_THREAD_STATE_PARKED   JVMTI_THREAD_STATE_PARKED

TM Thread states constants.

#define TM_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER   JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER

TM Thread states constants.

#define TM_THREAD_STATE_UNPARKED   0x0800

TM Thread states constants.

#define TM_THREAD_STATE_SUSPENDED   JVMTI_THREAD_STATE_SUSPENDED

TM Thread states constants.

#define TM_THREAD_STATE_INTERRUPTED   JVMTI_THREAD_STATE_INTERRUPTED

TM Thread states constants.

#define TM_THREAD_STATE_IN_NATIVE   JVMTI_THREAD_STATE_IN_NATIVE

TM Thread states constants.

#define TM_MUTEX_DEFAULT   0

TM Thread states constants.

#define TM_MUTEX_NESTED   1

TM Thread states constants.

#define TM_MUTEX_UNNESTED   2

TM Thread states constants.

#define WAIT_INTERRUPTABLE   1

TM Thread states constants.

#define WAIT_NONINTERRUPTABLE   0

TM Thread states constants.

#define TM_ERROR_NONE   (0)

TM functions error codes (they are mostly coming from APR).

#define TM_ERROR_INVALID_MONITOR   (50)

TM Thread states constants.

#define TM_ERROR_NOT_MONITOR_OWNER   (51)

TM Thread states constants.

#define TM_ERROR_INTERRUPT   (52)

TM Thread states constants.

#define TM_ERROR_NULL_POINTER   (100)

TM Thread states constants.

#define TM_ERROR_OUT_OF_MEMORY   (110)

TM Thread states constants.

#define TM_ERROR_ACCESS_DENIED   (111)

TM Thread states constants.

#define TM_ERROR_WRONG_PHASE   (112)

TM Thread states constants.

#define TM_ERROR_INTERNAL   (113)

TM Thread states constants.

#define TM_ERROR_UNATTACHED_THREAD   (115)

TM Thread states constants.

#define TM_ERROR_INVALID_ENVIRONMENT   (116)

TM Thread states constants.

#define TM_ERROR_MAX_THREADS   (117)

TM Thread states constants.

#define TM_ERROR_ILLEGAL_STATE   (51)

TM Thread states constants.

#define TM_ERROR_RUNNING_THREADS   (119)

TM Thread states constants.

#define TM_ERROR_EBUSY   APR_EBUSY

TM Thread states constants.

#define TM_ERROR_TIMEOUT   APR_TIMEUP

TM Thread states constants.

#define TM_ERROR_START   1000

TM Thread states constants.

#define TM_OS_ERROR   (TM_ERROR_START+1)

TM Thread states constants.

#define TM_DEFAULT_STACKSIZE   (512 * 1024)

TM Thread states constants.

#define TM_STATUS_WITHOUT_JAVA   0

TM Thread states constants.

#define TM_STATUS_ALLOCATED   1

TM Thread states constants.

#define TM_STATUS_INITIALIZED   2

TM Thread states constants.

#define TM_LIBRARY_STATUS_NOT_INITIALIZED   0

TM Thread states constants.

#define TM_LIBRARY_STATUS_INITIALIZED   1

TM Thread states constants.

#define TM_LIBRARY_STATUS_SHUTDOWN   2

TM Thread states constants.

Functions

Thread Manager initialization / shutdown

IDATA VMCALL hythread_global_lock ()

IDATA VMCALL hythread_global_unlock ()

void VMCALL hythread_init (hythread_library_t lib)

void VMCALL hythread_shutdown ()

void VMCALL hythread_shutdowning ()

int VMCALL hythread_lib_state ()

IDATA VMCALL hythread_lib_create (hythread_library_t *lib)

void VMCALL hythread_lib_destroy (hythread_library_t lib)

hythread_group_t VMCALL get_java_thread_group (void)

Basic manipulation

IDATA VMCALL hythread_create_ex (hythread_t new_thread, hythread_group_t group, UDATA stacksize, UDATA priority, hythread_wrapper_t wrapper, hythread_entrypoint_t func, void *data)

IDATA VMCALL hythread_attach_ex (hythread_t new_handle, hythread_library_t lib, hythread_group_t group)

void VMCALL hythread_detach_ex (hythread_t thread)

IDATA VMCALL hythread_set_to_group (hythread_t thread, hythread_group_t group)

IDATA VMCALL hythread_remove_from_group (hythread_t thread)

void VMCALL hythread_set_self (hythread_t thread)

UDATA VMCALL hythread_clear_interrupted_other (hythread_t thread)

void VMCALL hythread_yield_other (hythread_t thread)

IDATA VMCALL hythread_get_self_id ()

IDATA VMCALL hythread_get_id (hythread_t t)

hythread_t VMCALL hythread_get_thread (IDATA id)

IDATA VMCALL hythread_struct_init (hythread_t new_thread)

IDATA VMCALL hythread_struct_release (hythread_t thread)

IDATA VMCALL hythread_cancel_all (hythread_group_t group)

IDATA hythread_group_create (hythread_group_t *group)

IDATA VMCALL hythread_group_release (hythread_group_t group)

IDATA VMCALL hythread_group_get_list (hythread_group_t **list, int *size)

UDATA VMCALL hythread_tls_get_offset (hythread_tls_key_t key)

UDATA VMCALL hythread_tls_get_request_offset ()

UDATA VMCALL hythread_get_thread_times (hythread_t thread, int64 *pkernel, int64 *puser)

UDATA hythread_get_thread_stacksize (hythread_t thread)

UDATA VMCALL hythread_uses_fast_tls (void)

IDATA VMCALL hythread_get_hythread_offset_in_tls (void)

IDATA VMCALL hythread_get_struct_size ()

IDATA VMCALL hythread_thread_lock (hythread_t thread)

IDATA VMCALL hythread_thread_unlock (hythread_t thread)

IDATA VMCALL hythread_get_state (hythread_t thread)

IDATA VMCALL hythread_set_state (hythread_t thread, IDATA state)

int VMCALL hythread_reset_suspend_disable ()

void VMCALL hythread_set_suspend_disable (int count)

int VMCALL hythread_is_fat_lock (hythread_thin_monitor_t lockword)

hythread_monitor_t VMCALL hythread_inflate_lock (hythread_thin_monitor_t *lockword_ptr)

IDATA VMCALL hythread_owns_thin_lock (hythread_t thread, hythread_thin_monitor_t lockword)

IDATA VMCALL hythread_unreserve_lock (hythread_thin_monitor_t *lockword_ptr)

IDATA VMCALL hythread_get_thread_id_offset ()

IDATA VMCALL hythread_set_thread_stop_callback (hythread_t thread, hythread_event_callback_proc stop_callback)

IDATA VMCALL hythread_wait_for_nondaemon_threads (hythread_t thread, IDATA threads_to_keep)

IDATA VMCALL hythread_increase_nondaemon_threads_count (hythread_t thread)

IDATA VMCALL hythread_decrease_nondaemon_threads_count (hythread_t thread, IDATA threads_to_keep)

Conditional variable

IDATA VMCALL hycond_create (hycond_t *cond)

IDATA VMCALL hycond_wait (hycond_t *cond, hymutex_t *mutex)

IDATA VMCALL hycond_wait_timed (hycond_t *cond, hymutex_t *mutex, I_64 millis, IDATA nanos)

IDATA VMCALL hycond_wait_timed_raw (hycond_t *cond, hymutex_t *mutex, I_64 ms, IDATA nano)

IDATA VMCALL hycond_wait_interruptable (hycond_t *cond, hymutex_t *mutex, I_64 millis, IDATA nanos)

IDATA VMCALL hycond_notify (hycond_t *cond)

IDATA VMCALL hycond_notify_all (hycond_t *cond)

IDATA VMCALL hycond_destroy (hycond_t *cond)

Safe suspension support

hy_inline IDATA VMCALL hythread_is_suspend_enabled ()

Returns non-zero if thread is suspended.

hy_inline void VMCALL hythread_suspend_enable ()

Denotes the beginning of the code region where safe suspension is possible.

hy_inline void VMCALL hythread_suspend_disable ()

Denotes the end of the code region where safe suspension was possible.

void hythread_safe_point ()

Returns non-zero if thread is suspended.

void hythread_safe_point_other (hythread_t thread)

Returns non-zero if thread is suspended.

void VMCALL hythread_exception_safe_point ()

Returns non-zero if thread is suspended.

void VMCALL hythread_send_suspend_request (hythread_t thread)

Returns non-zero if thread is suspended.

IDATA VMCALL hythread_suspend_other (hythread_t thread)

Returns non-zero if thread is suspended.

IDATA VMCALL hythread_set_safepoint_callback (hythread_t thread, hythread_event_callback_proc callback)

Returns non-zero if thread is suspended.

IDATA VMCALL hythread_suspend_all (hythread_iterator_t *t, hythread_group_t group)

Returns non-zero if thread is suspended.

IDATA VMCALL hythread_resume_all (hythread_group_t group)

Returns non-zero if thread is suspended.

Latch

IDATA VMCALL hylatch_create (hylatch_t *latch, IDATA count)

IDATA VMCALL hylatch_wait (hylatch_t latch)

IDATA VMCALL hylatch_wait_timed (hylatch_t latch, I_64 ms, IDATA nano)

IDATA VMCALL hylatch_wait_interruptable (hylatch_t latch, I_64 ms, IDATA nano)

IDATA VMCALL hylatch_set (hylatch_t latch, IDATA count)

IDATA VMCALL hylatch_count_down (hylatch_t latch)

IDATA VMCALL hylatch_get_count (IDATA *count, hylatch_t latch)

IDATA VMCALL hylatch_destroy (hylatch_t latch)

Thread iterator support

hythread_iterator_t VMCALL hythread_iterator_create (hythread_group_t group)

IDATA VMCALL hythread_iterator_release (hythread_iterator_t *it)

IDATA VMCALL hythread_iterator_reset (hythread_iterator_t *it)

hythread_t VMCALL hythread_iterator_next (hythread_iterator_t *it)

IDATA VMCALL hythread_iterator_has_next (hythread_iterator_t it)

IDATA VMCALL hythread_iterator_size (hythread_iterator_t iterator)

Semaphore

IDATA hysem_create (hysem_t *sem, UDATA initial_count, UDATA max_count)

IDATA VMCALL hysem_wait_timed (hysem_t sem, I_64 ms, IDATA nano)

IDATA VMCALL hysem_wait_interruptable (hysem_t sem, I_64 ms, IDATA nano)

IDATA VMCALL hysem_getvalue (IDATA *count, hysem_t sem)

IDATA hysem_set (hysem_t sem, IDATA count)

Mutex

IDATA hymutex_create (hymutex_t *mutex, UDATA flags)

IDATA hymutex_lock (hymutex_t *mutex)

IDATA hymutex_trylock (hymutex_t *mutex)

IDATA hymutex_unlock (hymutex_t *mutex)

IDATA hymutex_destroy (hymutex_t *mutex)

Thin monitors support

IDATA VMCALL hythread_thin_monitor_create (hythread_thin_monitor_t *lockword)

IDATA VMCALL hythread_thin_monitor_enter (hythread_thin_monitor_t *lockword)

IDATA VMCALL hythread_thin_monitor_try_enter (hythread_thin_monitor_t *lockword)

IDATA VMCALL hythread_thin_monitor_exit (hythread_thin_monitor_t *lockword)

IDATA VMCALL hythread_thin_monitor_release (hythread_thin_monitor_t *lockword)

IDATA VMCALL hythread_thin_monitor_wait (hythread_thin_monitor_t *lockword)

IDATA VMCALL hythread_thin_monitor_wait_timed (hythread_thin_monitor_t *lockword_ptr, I_64 ms, IDATA nano)

IDATA VMCALL hythread_thin_monitor_wait_interruptable (hythread_thin_monitor_t *lockword_ptr, I_64 ms, IDATA nano)

IDATA VMCALL hythread_thin_monitor_notify (hythread_thin_monitor_t *lockword)

IDATA VMCALL hythread_thin_monitor_notify_all (hythread_thin_monitor_t *lockword)

IDATA VMCALL hythread_thin_monitor_destroy (hythread_thin_monitor_t *lockword)

hythread_t VMCALL hythread_thin_monitor_get_owner (hythread_thin_monitor_t *lockword)

IDATA VMCALL hythread_thin_monitor_get_recursion (hythread_thin_monitor_t *lockword)

void VMCALL hythread_native_resource_is_live (U_32)

void VMCALL hythread_reclaim_resources ()

Define Documentation

#define HYTHREAD_EXT_H

#define LOCK_RESERVATION

Opaque structures.

#define TM_THREAD_QUANTITY_OF_PREDEFINED_TLS_KEYS 1

#define TM_THREAD_STATE_NEW 0

TM Thread states constants.