Local Reference and Global Reference

 本文来自：IBM Knowledge Center  
 https://www-01.ibm.com/support/knowledgecenter/SSYKE2_7.0.0/com.ibm.java.lnx.71.doc/diag/understanding/jni_transitions_j2j_n2n.html?lang=en

Local references are scoped to their creating stack frame and thread, and automatically deleted when their creating stack frame returns. Global references allow native code to promote a local reference into a form usable by native code in any thread attached to the JVM.
Global references and memory leaks

JNI transitions

To understand JNI local reference management and the GC, you must understand the context of a running thread attached to the JVM.

Every thread has a runtime stack that includes a frame for each method call.

From a GC perspective, every stack establishes a thread-specific "root set" including the union of all JNI local references in the stack.

Each method call in a running VM adds (pushes) a frame onto the stack, just as every return removes (pops) a frame.

Each call point in a running stack can be characterized as one of the following types:

Java to Java (J2J)
Native to Native (N2N)
Java to Native (J2N)
Native to Java (N2J)

.

J2J and N2N transitions
Because object references do not change form as part of J2J or N2N transitions, J2J and N2N transitions do not affect JNI local reference management.

N2J transitions
For native code to call Java code (N2J) in the current thread, the thread must first be attached to the JVM in the current process.
Every N2J call that passes object references must have obtained them using JNI, therefore they are either valid local or global JNI refs. Any object references returned from the call are JNI local references.

J2N calls
The JVM must ensure that objects passed as parameters from Java? to the native method and any new objects created by the native code remain reachable by the GC.
To handle the GC requirements, the JVM allocates a small region of specialized storage called a local reference root set.

J2N calls
The JVM must ensure that objects passed as parameters from Java? to the native method and any new objects created by the native code remain reachable by the GC.
To handle the GC requirements, the JVM allocates a small region of specialized storage called a local reference root set.

A local reference root set is created when:

A thread is first attached to the JVM (the outermost root set of the thread).
Each J2N transition occurs.
The JVM initializes the root set created for a J2N transition with:

A local reference to the caller's object or class.
A local reference to each object passed as a parameter to the native method.

.

New local references created in native code are added to this J2N root set, unless you create a new local frame using the PushLocalFrame JNI function.

The default root set is large enough to contain 16 local references per J2N transition. The -Xcheck:jni command-line option causes the JVM to monitor JNI usage.

hen -Xcheck:jni is used, the JVM writes a warning message when more than 16 local references are required at run time.
If you receive this warning message, use one of the following JNI functions to manage local references more explicitly:

NewLocalRef
DeleteLocalRef
PushLocalFrame
PopLocalFrame
EnsureLocalCapacity

为了理解JNI local reference 管理和GC垃圾收集，必须了解一个在JVM中一个运行线程的上下文。

当一个方法调用时,该线程就会创建一个包含“帧”的运行时栈 。 从GC来讲，每一个栈都建立一个线程 “根集合”。“根集合”包括在该栈中的所有jni local reference.

在一个运行中的VM来讲，每次调用方法都会在栈中增加一“帧”,当方法返回时都从栈中移除一“帧”。每次调用类型如下 ：

Java to Java (J2J)
Native to Native (N2N)
Java to Native (J2N)
Native to Java (N2J)

J2J 和N2N 交换：因为J2J 和N2N在交换时,对象的引用不会发生改变，所有J2J和N2N交换不会影响到JNI local reference的管理。

N2J交换：在当前线程中，native code调用java code方法（N2J）,当每次N2J调用时,必须使用JNI方法来获取引用来传递到java Code中，所以，即可以存在local reference 或者global reference . 任何通过 JNI方法返回的对象引用都是JNI local reference .

J2N交换： java 虚拟机必须保证每一个由java code中的对象作为参数传递到native code 和任何通过native  code创建的新对象都必须可以通过GC是可以到达的。

为了满足GC的需求，java虚拟机分配一个很小的特殊区域来存储  local  reference  set 。

一个local  reference set在如下情况下会被创建：

1-当一个线程第一次连接到JVM

2-每一次J2N 函数调用

JVM为了J2N交换初始化：1 -一个对于调用对象或者类的local reference  2-每一个当做参传递到native code方法中的local reference.

通过native code创建的每一个新local  reference 都被增加到J2N root set中。默认的local reference 最大存储16个local reference.