Old Text

Weak Global References

Weak global references in JNI are a simplified version of the Java Weak References, available as part of the Java 2 Platform API ( java.lang.ref package and its classes).

Clarification    (added June 2001)

Since garbage collection may occur while native methods are running, objects referred to by weak global references can be freed at any time. While weak global references can be used where global references are used, it is generally inappropriate to do so, as they may become functionally equivalent to NULL without notice.

While IsSameObject can be used to determine whether a weak global reference refers to a freed object, it does not prevent the object from being freed immediately thereafter. Consequently, programmers may not rely on this check to determine whether a weak global reference may used (as a non-NULL reference) in any future JNI function call.

To overcome this inherent limitation, it is recommended that a standard (strong) local or global reference to the same object be acquired using the JNI functions NewLocalRef or NewGlobalRef, and that this strong reference be used to access the intended object. These functions will return NULL if the object has been freed, and otherwise will return a strong reference (which will prevent the object from being freed). The new reference should be explicitly deleted when immediate access to the object is no longer required, allowing the object to be freed.

The weak global reference is weaker than other types of weak references (Java objects of the SoftReference or WeakReference classes). A weak global reference to a specific object will not become functionally equivalent to NULL until after SoftReference or WeakReference objects referring to that same specific object have had their references cleared.

The weak global reference is weaker than Java's internal references to objects requiring finalization. A weak global reference will not become functionally equivalent to NULL until after the completion of the finalizer for the referenced object, if present.

Interactions between weak global references and PhantomReferences are undefined. In particular, implementations of a Java VM may (or may not) process weak global references after PhantomReferences, and it may (or may not) be possible to use weak global references to hold on to objects which are also referred to by PhantomReference objects. This undefined use of weak global references should be avoided.

New Text

Weak Global References

Weak global references are a special kind of global reference. Unlike normal global references, a weak global reference allows the underlying Java object to be garbage collected. Weak global references may be used in any situation where global or local references are used.

Weak global references are related to Java phantom references (java.lang.ref.PhantomReference). A weak global reference to a specific object is treated as a phantom reference referring to that object when determining whether the object is phantom reachable (see java.lang.ref). Such a weak global reference will become functionally equivalent to NULL at the same time as a PhantomReference referring to that same object would be cleared by the garbage collector.

Since garbage collection may occur while native methods are running, objects referred to by weak global references can be freed at any time. While weak global references can be used where global references are used, it is generally inappropriate to do so, as they may become functionally equivalent to NULL without notice.

IsSameObject can be used to compare a weak global reference to a non-NULL local or global reference. If the objects are the same, the weak global reference won't become functionally equivalent to NULL so long as the other reference has not been deleted.

IsSameObject can also be used to compare a weak global reference to NULL to determine whether the underlying object has been freed. However, programmers should not rely on this check to determine whether a weak global reference may be used (as a non-NULL reference) in any future JNI function call, since an intervening garbage collection could change the weak global reference.

Instead, it is recommended that a (strong) local or global reference to the underlying object be acquired using one of the JNI functions NewLocalRef or NewGlobalRef. These functions will return NULL if the object has been freed. Otherwise, the new reference will prevent the underlying object from being freed. The new reference, if non-NULL, can then be used to access the underlying object, and deleted when such access is no longer needed.