JNIEnvironment (Jikes RVM API)

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

public final class JNIEnvironment
extends Object

A JNIEnvironment is created for each Java thread.

Field Summary

Fields
Modifier and Type	Field and Description
`private boolean`	`alwaysHasNativeFrame` true if the bottom stack frame is native, such as thread for CreateJVM or AttachCurrentThread
`private Address`	`basePointerOnEntryToNative` When native code doesn't maintain a base pointer we can't chain through the base pointers when walking the stack.
`private Address`	`externalJNIFunctions` This is the pointer to the shared JNIFunction table.
`private int`	`hasPendingException`
`static FunctionTable`	`JNIFunctions` This is the shared JNI function table used by native code to invoke methods in @link{JNIFunctions}.
`AddressArray`	`JNIRefs` references passed to native code
`protected static int`	`JNIREFS_ARRAY_LENGTH` initial size for JNI refs, later grow as needed
`protected static 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).
`protected int`	`JNIRefsMax` Offset of end (last entry) of JNIRefs array
`int`	`JNIRefsSavedFP` Previous frame boundary in JNIRefs array.
`private AddressArray`	`JNIRefsShadow`
`int`	`JNIRefsTop` Offset of current top ref in JNIRefs array
`private 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.
`static LinkageTripletTable`	`linkageTriplets` For the 64-bit PowerPC ELF ABI we need a linkage triple instead of just a function pointer.
`private Throwable`	`pendingException` Currently pending exception (null if none)
`private Address`	`savedJTOC` For saving JTOC register on entry to native, to be restored on JNI call from native (only used on PowerPC)
`protected RVMThread`	`savedTRreg` For saving processor register on entry to native, to be restored on JNI call from native

Constructor Summary

Constructors
Constructor and Description

JNIEnvironment()
Initialize a thread specific JNI environment.

Constructors
Constructor and Description
`JNIEnvironment()` Initialize a thread specific JNI environment.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static void`	`boot()` Initialization required during VM booting; only does something if we are on a platform that needs linkage triplets.
`private void`	`checkPush(Object ref, boolean canGrow)` Check push of reference can succeed
`void`	`deleteJNIRef(int offset)` Remove a reference from the JNIRefs stack.
`void`	`dumpJniRefsStack()` Dump the JNIRefs stack to the sysWrite stream
`void`	`entryToJNI(int encodedReferenceOffsets)` Save data and perform necessary conversions for entry into JNI.
`Object`	`exitFromJNI(int offset)` Restore data, throw pending exceptions or convert return value for exit from JNI.
`Throwable`	`getException()`
`Object`	`getJNIRef(int offset)` Get a reference from the JNIRefs stack.
`boolean`	`hasNativeStackFrame()`
`static void`	`initFunctionTable(FunctionTable functions)` Initialize the array of JNI functions.
`int`	`pushJNIRef(Object ref)` Push a reference onto thread local JNIRefs stack.
`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
`AddressArray`	`refsArray()`
`int`	`refsTop()`
`private void`	`replaceJNIRefs(AddressArray newrefs)` Atomically copies and installs a new JNIRefArray.
`int`	`savedRefsFP()`
`static void`	`throwPendingException()` Return and clear the (known to be non-null) pending exception.
`Address`	`topJavaFP()`
`private int`	`uninterruptiblePushJNIRef(Address ref, boolean isRef)` Push a JNI ref, used on entry to JNI NB only used for Intel

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - 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 64-bit PowerPC ELF ABI 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
```
private 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
```
private Throwable pendingException
```
    Currently pending exception (null if none)
  - hasPendingException
```
private int hasPendingException
```
  - alwaysHasNativeFrame
```
private final 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
  - JNIRefsShadow
```
private AddressArray JNIRefsShadow
```
  - 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
- Constructor Detail
  - JNIEnvironment
```
public JNIEnvironment()
```
    Initialize a thread specific JNI environment.
- Method Detail
  - 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
  - replaceJNIRefs
```
private void replaceJNIRefs(AddressArray newrefs)
```
    Atomically copies and installs a new JNIRefArray.
    
    Parameters:
    
    newrefs - the new JNIRefArray
  - 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
    
    Returns:
    
    new offset of current top in JNIRefs array or 0 if the reference is zero and a framepointer
  - 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
  - throwPendingException
```
public static void throwPendingException()
```
    Return and clear the (known to be non-null) pending exception.
  - 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.
    
    Parameters:
    
    functions - the function table to initialize
  - boot
```
public static void boot()
```
    Initialization required during VM booting; only does something if we are on a platform that needs linkage triplets.

Class JNIEnvironment

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

JNIREFS_ARRAY_LENGTH

JNIREFS_FUDGE_LENGTH

JNIFunctions

linkageTriplets

externalJNIFunctions

savedTRreg

savedJTOC

basePointerOnEntryToNative

JNITopJavaFP

pendingException

hasPendingException

alwaysHasNativeFrame

JNIRefs

JNIRefsShadow

JNIRefsTop

JNIRefsMax

JNIRefsSavedFP

Constructor Detail

JNIEnvironment

Method Detail

hasNativeStackFrame

topJavaFP

refsArray

refsTop

savedRefsFP

checkPush

pushJNIRef

replaceJNIRefs

uninterruptiblePushJNIRef

entryToJNI

exitFromJNI

getJNIRef

deleteJNIRef

dumpJniRefsStack

recordException

throwPendingException

getException

initFunctionTable

boot