org.jikesrvm.jni
Class JNIEnvironment

java.lang.Object
  org.jikesrvm.jni.JNIEnvironment

All Implemented Interfaces:

SizeConstants

public final class JNIEnvironment
extends Object
implements SizeConstants

A JNIEnvironment is created for each Java thread.

JNIREFS_ARRAY_LENGTH

protected static final int JNIREFS_ARRAY_LENGTH

initial size for JNI refs, later grow as needed

See Also:

Constant Field Values

JNIREFS_FUDGE_LENGTH

protected static final int JNIREFS_FUDGE_LENGTH

sometimes we put stuff onto the jnirefs array bypassing the code that makes sure that it does not overflow (evil assembly code in the jni stubs that would be painful to fix). So, we keep some space between the max value in JNIRefsMax and the actual size of the array. How much is governed by this field.

See Also:

Constant Field Values

JNIFunctions

public static FunctionTable JNIFunctions

This is the shared JNI function table used by native code to invoke methods in @link{JNIFunctions}.

LinkageTriplets

public static LinkageTripletTable LinkageTriplets

For the PowerOpenABI we need a linkage triple instead of just a function pointer. This is an array of such triples that matches JNIFunctions.

externalJNIFunctions

private final Address externalJNIFunctions

This is the pointer to the shared JNIFunction table. When we invoke a native method, we adjust the pointer we pass to the native code such that this field is at offset 0. In other words, we turn a JNIEnvironment into a JNIEnv* by handing the native code an interior pointer to this object that points directly to this field.

savedTRreg

protected RVMThread savedTRreg

For saving processor register on entry to native, to be restored on JNI call from native

savedJTOC

private final Address savedJTOC

For saving JTOC register on entry to native, to be restored on JNI call from native (only used on PowerPC)

basePointerOnEntryToNative

private Address basePointerOnEntryToNative

When native code doesn't maintain a base pointer we can't chain through the base pointers when walking the stack. This field holds the basePointer on entry to the native code in such a case, and is pushed onto the stack if we re-enter Java code (e.g. to handle a JNI function). This field is currently only used on IA32.

JNITopJavaFP

protected Address JNITopJavaFP

When transitioning between Java and C and back, we may want to stop a thread returning into Java and executing mutator code when a GC is in progress. When in C code, the C code may never return. In these situations we need a frame pointer at which to begin scanning the stack. This field holds this value. NB. these fields don't chain together on the stack as we walk through native frames by knowing their return addresses are outside of our heaps

pendingException

protected Throwable pendingException

Currently pending exception (null if none)

next

protected JNIEnvironment next

We allocate JNIEnvironments in the immortal heap (so we can hand them directly to C code). Therefore, we must do some kind of pooling of JNIEnvironment instances. This is the free list of unused instances.

pool

protected static JNIEnvironment pool

Pool of available JNIEnvironments.

alwaysHasNativeFrame

protected boolean alwaysHasNativeFrame

true if the bottom stack frame is native, such as thread for CreateJVM or AttachCurrentThread

JNIRefs

public AddressArray JNIRefs

references passed to native code

JNIRefsTop

public int JNIRefsTop

Offset of current top ref in JNIRefs array

JNIRefsMax

protected int JNIRefsMax

Offset of end (last entry) of JNIRefs array

JNIRefsSavedFP

public int JNIRefsSavedFP

Previous frame boundary in JNIRefs array. NB unused on IA32

JNIEnvironment

public JNIEnvironment()

initializeState

protected void initializeState()

Initialize a thread specific JNI environment.

allocateEnvironment

public static JNIEnvironment allocateEnvironment()

Create a thread specific JNI environment.

deallocateEnvironment

public static void deallocateEnvironment(JNIEnvironment env)

Return a thread-specific JNI environment; must be called as part of terminating a thread that has a JNI environment allocated to it.

Parameters:

env - the JNIEnvironment to deallocate

hasNativeStackFrame

public boolean hasNativeStackFrame()

topJavaFP

public Address topJavaFP()

refsArray

public AddressArray refsArray()

refsTop

public int refsTop()

savedRefsFP

public int savedRefsFP()

checkPush

private void checkPush(Object ref,
                       boolean canGrow)

Check push of reference can succeed

Parameters:

ref - object to be pushed

canGrow - can the JNI reference array be grown?

pushJNIRef

public int pushJNIRef(Object ref)

Push a reference onto thread local JNIRefs stack. To be used by JNI functions when returning a reference back to JNI native C code.

Parameters:

ref - the object to put on stack

Returns:

offset of entry in JNIRefs stack

uninterruptiblePushJNIRef

private int uninterruptiblePushJNIRef(Address ref,
                                      boolean isRef)

Push a JNI ref, used on entry to JNI NB only used for Intel

Parameters:

ref - reference to place on stack or value of saved frame pointer

isRef - false if the reference isn't a frame pointer

entryToJNI

public void entryToJNI(int encodedReferenceOffsets)

Save data and perform necessary conversions for entry into JNI. NB only used for Intel.

Parameters:

encodedReferenceOffsets - bit mask marking which elements on the stack hold objects that need encoding as JNI ref identifiers

exitFromJNI

public Object exitFromJNI(int offset)

Restore data, throw pending exceptions or convert return value for exit from JNI. NB only used for Intel.

Parameters:

offset - offset into JNI reference tables of result

Returns:

Object encoded by offset or null if offset is 0

getJNIRef

public Object getJNIRef(int offset)

Get a reference from the JNIRefs stack.

Parameters:

offset - in JNIRefs stack

Returns:

reference at that offset

deleteJNIRef

public void deleteJNIRef(int offset)

Remove a reference from the JNIRefs stack.

Parameters:

offset - in JNIRefs stack

dumpJniRefsStack

public void dumpJniRefsStack()

Dump the JNIRefs stack to the sysWrite stream

recordException

public void recordException(Throwable e)

Record an exception as pending so that it will be delivered on the return to the Java caller; clear the exception by recording null

Parameters:

e - An exception or error

getException

public Throwable getException()

Returns:

the pending exception

initFunctionTable

public static void initFunctionTable(FunctionTable functions)

Initialize the array of JNI functions. This function is called during bootimage writing.

boot

public static void boot()

Initialization required during VM booting; only does something if we are on a platform that needs linkage triplets.