…or, solving the problem of how to delete local references when the execution context isn’t clear.
JNI includes notions of “local” and “global” references. Loosely speaking, local references correspond to those that are local to the scope of a function; and global references correspond to those that persist outside the scope of a function. When Java calls a native method, it provides the native code with at stack frame where local references can be stored. The native code can then proceed to make calls to JNI functions which, in general, return local references. These local references are automatically stored in the stack frame; and the Java runtime takes care of cleaning them up when it pops the stack frame upon leaving the native method implementation.
So far, so good. But not all JNI function calls occur in response to Java calling a native method implementation. In fact, if you’re starting up the VM via JNI, you probably end up calling JNI functions that return local references just the same. Only in this case, the Java runtime hasn’t provided you with a stack frame that it will magically clean up once your code is done executing. Instead, you’ll need to delete the local references explicitly.
Thus we have two very different ways local references must be handled, depending on the context of the JNI function calls. And the inevitable problem: in a utility function which might be called from either context, how should intermediate local references be handled? Consider a function that creates a java.net.URL instance:
jobject create_url(JNIEnv & env, const char * const url)
{
const jstring url_string = env.NewStringUTF(url);
if (!url_string) {
env.ExceptionClear();
throw std::runtime_error("failed to construct string for URL");
}
const jclass url_class = env.FindClass("java/net/URL");
if (!url_class) {
env.ExceptionClear();
throw std::runtime_error("could not find java.net.URL class");
}
const jmethodID ctor_id =
env.GetMethodID(url_class, "", "(Ljava/lang/String;)V");
if (!ctor_id) {
env.ExceptionClear();
throw std::runtime_error("failed to get "
"java.net.URL.URL(java.lang.String) "
"constructor");
}
const jobject url_obj =
env.NewObject(url_class, ctor_id, url_string);
if (!url_obj) {
env.ExceptionClear();
throw std::runtime_error("could not create java.net.URL "
"instance");
}
return url_obj;
}
The above code will work just fine when it is called from a native method implementation. But if it is called outside that context, it will leak the local references corresponding to url_string and url_class. (We can assume the caller has responsibility for the local reference corresponding to url_obj in both cases.)
So, let’s toss in the code to delete the local references. We need to be exception-safe, so let’s use ScopeGuard:
jobject create_url(JNIEnv & env, const char * const url)
{
const jstring url_string = env.NewStringUTF(url);
if (!url_string) {
env.ExceptionClear();
throw std::runtime_error("failed to construct string for URL");
}
scope_guard url_string_guard =
make_obj_guard(env, &JNIEnv::DeleteLocalRef, url_string);
const jclass url_class = env.FindClass("java/net/URL");
if (!url_class) {
env.ExceptionClear();
throw std::runtime_error("could not find java.net.URL class");
}
scope_guard url_class_guard =
make_obj_guard(env, &JNIEnv::DeleteLocalRef, url_class);
const jmethodID ctor_id =
env.GetMethodID(url_class, "", "(Ljava/lang/String;)V");
if (!ctor_id) {
env.ExceptionClear();
throw std::runtime_error("failed to get "
"java.net.URL.URL(java.lang.String) "
"constructor");
}
const jobject url_obj =
env.NewObject(url_class, ctor_id, url_string);
if (!url_obj) {
env.ExceptionClear();
throw std::runtime_error("could not create java.net.URL "
"instance");
}
return url_obj;
}
There. Now we can call the function outside a native method implementation. But in making that work, we’ve made the function unusable from within a native method implementation. Clearly we need to make the calls to JNIEnv::DeleteLocalRef conditional; and we’ll have to let the caller tell us what context the function is being called in.
jobject create_url(JNIEnv & env,
const char * const url,
const bool delete_local_refs)
{
const jstring url_string = env.NewStringUTF(url);
if (!url_string) {
env.ExceptionClear();
throw std::runtime_error("failed to construct string for URL");
}
scope_guard url_string_guard =
make_obj_guard(env, &JNIEnv::DeleteLocalRef, url_string);
if (!delete_local_refs) { url_string_guard.dismiss(); }
const jclass url_class = env.FindClass("java/net/URL");
if (!url_class) {
env.ExceptionClear();
throw std::runtime_error("could not find java.net.URL class");
}
scope_guard url_class_guard =
make_obj_guard(env, &JNIEnv::DeleteLocalRef, url_class);
if (!delete_local_refs) { url_class_guard.dismiss(); }
const jmethodID ctor_id =
env.GetMethodID(url_class, "", "(Ljava/lang/String;)V");
if (!ctor_id) {
env.ExceptionClear();
throw std::runtime_error("failed to get "
"java.net.URL.URL(java.lang.String) "
"constructor");
}
const jobject url_obj =
env.NewObject(url_class, ctor_id, url_string);
if (!url_obj) {
env.ExceptionClear();
throw std::runtime_error("could not create java.net.URL "
"instance");
}
return url_obj;
}
Well, there we are. It’s exception-safe and the caller can tell it the Right Thing to do. But…It sure does Suck.
- It relies on the caller telling it to do the right thing; which means it’s pretty easy to use wrong.
- We wind up having to check
delete_local_refs at each point where we might (or might not) need to call JNIEnv::DeleteLocalRefs. Our need for exception-safety prevents us from consolidating this logic near the end of the function. Consequently, the code is interspersed with yet more error handling logic that gets in the way of understanding the function’s primary logic when reading the code.
So, is there a better way? Fortunately, yes.
JNI provides functions that allow us to create (and destroy) stack frames for local references, JNIEnv::PushLocalFrame and JNIEnv::PopLocalFrame. So, instead of relying on a stack frame that may or may not be there depending on the calling context, we can just create our own, regardless.
jobject create_url(JNIEnv & env, const char * const url)
{
if (env.PushLocalFrame(3) < 0) { return 0; }
scope_guard local_frame_guard =
make_obj_guard(env, &JNIEnv::PopLocalFrame, 0);
const jstring url_string = env.NewStringUTF(url);
if (!url_string) {
env.ExceptionClear();
throw std::runtime_error("failed to construct string for URL");
}
const jclass url_class = env.FindClass("java/net/URL");
if (!url_class) {
env.ExceptionClear();
throw std::runtime_error("could not find java.net.URL class");
}
const jmethodID ctor_id =
env.GetMethodID(url_class, "", "(Ljava/lang/String;)V");
if (!ctor_id) {
env.ExceptionClear();
throw std::runtime_error("failed to get "
"java.net.URL.URL(java.lang.String) "
"constructor");
}
const jobject url_obj =
env.NewObject(url_class, ctor_id, url_string);
if (!url_obj) {
env.ExceptionClear();
throw std::runtime_error("could not create java.net.URL "
"instance");
}
return url_obj;
}
Once again, we use ScopeGuard; only now we’re using it to call JNIEnv::PopLocalFrame. Note that we’ve provided space for three local references in our frame, corresponding to url_string, url_class, and url_obj.
But the above code is horribly broken: when we return from the function, the local reference associated with url_obj gets cleaned up with all the others! So, how do we get this reference out of our local frame and return it, unbound, to the caller?
The solution is a temporary global reference. We can convert url_obj to a global reference for the remaining duration of the local frame; and then convert it back to a local reference before returning to the caller. Once more, ScopeGuard is our friend:
jobject create_url(JNIEnv & env, const char * const url)
{
using boost::ref;
//
// We can safely run DeleteGlobalRef in the scope guard because
// calling DeleteGlobalRef with 0 is a no-op.
//
jobject result_global_ref = 0;
scope_guard result_global_ref_guard =
make_obj_guard(env,
&JNIEnv::DeleteGlobalRef,
ref(result_global_ref));
{
if (env.PushLocalFrame(3) < 0) { return 0; }
scope_guard local_frame_guard =
make_obj_guard(env, &JNIEnv::PopLocalFrame, 0);
const jstring url_string = env.NewStringUTF(url);
if (!url_string) {
env.ExceptionClear();
throw std::runtime_error("failed to construct string for URL");
}
const jclass url_class = env.FindClass("java/net/URL");
if (!url_class) {
env.ExceptionClear();
throw std::runtime_error("could not find java.net.URL class");
}
const jmethodID ctor_id =
env.GetMethodID(url_class, "", "(Ljava/lang/String;)V");
if (!ctor_id) {
env.ExceptionClear();
throw std::runtime_error("failed to get "
"java.net.URL.URL(java.lang.String) "
"constructor");
}
const jobject url_obj =
env.NewObject(url_class, ctor_id, url_string);
if (!url_obj) {
env.ExceptionClear();
throw std::runtime_error("could not create java.net.URL "
"instance");
}
//
// Create a global reference so that the new object will outlive
// the local frame.
//
result_global_ref = env.NewGlobalRef(url_obj);
if (!result_global_ref) { return 0; }
}
//
// NewLocalRef does not throw any Java exceptions.
//
const jobject result = env.NewLocalRef(result_global_ref);
if (!result) { throw std::bad_alloc(); }
return result;
}
Ta da. We introduce an additional block scope for the duration of our local stack frame. We propagate the reference to the URL class instance out of the frame’s lifetime by creating an additional global reference. Once the frame is destroyed, this global reference is all that’s left. We then create a new local reference to return to the caller, and let a scope guard take care of cleaning up the global reference.