The Native Shim

The first step will be to complete the AcmeProximitySensor class, shown in part in Listing 9.6. It is the shim that connects the Java environment to the native environment.

It is very much best practice that the shim code abstract away even the faintest whiff of native-ness. The API for the shim should follow all the best practices standard for any Java API. In particular, declaring the API in a mockable Java interface is a great way to make it possible to test client code without requiring access to any specific hardware.

Listing 9.9 shows a complete implementation of the AcmeProximitySensor class.

Listing 9.9 Proximity HAL Java Implementation

Click here to view code image

public class AcmeProximitySensor implements AutoCloseable {
    static { System.loadLibrary(“acmeproximityjni”); }

    private long peer;

    public void init() throws IOException {
        synchronized (this) {
            if (peer != 0L) { return; }
            peer = open();
            if (peer == 0L) {
                throw new IOException(“Failed to open proximity sensor”);
            }
        }
    }
    
    public int poll(int precision) throws IOException {
        synchronized (this) {
            if (peer == 0L) { throw new IOException(“Device not open”); }
            return poll(peer, precision);
        }
    }

    @Override
    public void close() throws IOException {
        final long hdl;
        synchronized (this) {
            hdl = peer;
            peer = 0L;
        }
        if (hdl == 0L) { return; }
        if (close(hdl) < 0) {
            throw new IOException(“Failed closing proximity sensor”);
        }
    }

    @Override
    protected void finalize() throws Throwable {
        try { close(); }
        finally { super.finalize(); }
    }

    private static native long open();

    private static native int poll(long handle, int precision);

    private static native int close(long handle);
}

There are several things to note in this code.

The first is the use of the previously discussed System.loadLibrary method. It is called, as is frequently the case, from a static initializer that will be invoked when the class is loaded. This is a common strategy because the library must be loaded before any of the methods in the class can be used.

There are other strategies, though. A system that requires several native libraries may load them all at once, perhaps using some kind of registration system, as part of startup. Another possibility, especially in systems that require additional initialization, is loading necessary native libraries in an initialization method that client code must call explicitly before making any other use of the library.

Note, also, that System.loadLibrary loads the library named in its actual parameter in a system-dependent way. It modifies the name to conform to the platform library naming conventions and then attempts to load it from the library path. When run on a Linux OS, for example, the code in Listing 9.9 will load the libacmeproximityjni.so library. On a Windows system, though, it would load the acmeproximityjni.dll library.

The library path can be specified at JVM startup using the system parameter java.library.path or, on Android Linux, by setting the environment variable LD_LIBRARY_PATH. A second method, System.load, mentioned previously, will load a library from a specific file named in the fully qualified path passed as its argument.

Next, observe the use of the variable peer. In this code, the Java long variable peer contains the native reference to the HAL object as described in the discussion of Listing 9.8. Unlike C, in which a reference can be made opaque by declaring it void*, making a reference opaque in Java is fairly difficult. Nonetheless, it is crucial that the contents of a variable used in this way be treated as opaque. Any mutation of any kind by the Java code is almost certainly an error and probably a disastrous one. As usual, in situations like this, minimizing visibility and mutability is a useful strategy.

Together, Listings 9.8 and 9.9 illustrate the simplest form of a very common pattern. The responsibility for managing the Java use of specialized hardware is handled through the coordination of two objects, one Java and one native. The two objects are the two ends of a bridge—one end in the native code and the other in the Java code—through which all interactions take place. Client code instantiates the Java object and the Java object manages the native object, frequently called a native peer, or a companion object. The Java code holds a reference to the native object. The native code’s awareness of the Java code is kept minimal.

The Native Shim: Opaque Peer

Another example of this pattern attempts to enforce the opacity of the native reference in the Java variable by using reflection in the native code to set the value of the reference held in the Java variable. Listings 9.10 and 9.11 illustrate this technique.

Listing 9.10 Opaque Peer: Native

Click here to view code image

JNIEXPORT int
JNICALL Java_com_acme_device_proximity_AcmeProximitySensor_open
    (JNIEnv *env, jclass klass, jobject instance) {

    if (hw_get_module(ACME_PROXIMITY_SENSOR_MODULE, &module))
        return -1;

    hw_device_t *device;
    if (module->methods->open(module, nullptr, &device)))
        return -2;

    jfieldID peer = env->GetFieldID(klass, "peer", "J");
    if (!peer)
        return -3;

    env->SetLongField(instance, peer, reinterpret_cast<jlong>(mem));
    
    return 0;
}

Listing 9.11 Opaque Peer: Java

Click here to view code image

public class AcmeProximitySensor implements AutoCloseable {
    /...
    
    private long peer;

    /...

    public void init() throws IOException {
        synchronized (this) {
            int status = open(this);
            if (status != 0) {
                throw new IOException(
                    "Failed to open proximity sensor: " + status);
            }
        }
    }

    /...

    private static native int open(AcmeProximitySensor instance);
    
    /...
}

Two new JNI methods are used here without introduction: GetFieldID and SetLongField. Their names, though, are fairly self-explanatory (they return a reference to a Java field and assign the field value, respectively) so that the concept the listing introduces should be clear.

The open method in Listing 9.11 could, as easily, be an instance method instead of a static method. In JNI, the difference between the implementations of a static and an instance method is the second argument to the method. The second argument to a static native function is a reference to the class to which the function belongs. The second argument to an instance native function is a reference to the instance to which the function belongs. Holding a reference to the instance means that the native code can access the instance’s fields, exactly as the example code does.

In this case, however, we also need a reference to the object’s class (for the call to GetFieldID). Because both are needed, using a static method (which provides the reference to the class object) will work just as well. We pass the instance reference (this in the call to open, in
Listing 9.11) explicitly. The native implementation then has both of the references that it needs.

Although somewhat more complex, the strategy illustrated in Listings 9.10 and 9.11 has advantages. In this implementation, any Java use of the variable peer is now clearly an error. Distinguishing between appropriate and inappropriate use of the stored pointer is not necessary: Any use is an error. Another advantage is that the open method’s return value is now, unambiguously, a status code. No need exists to partition returns into legal values and illegal values.

The Native Shim: Finalization

Returning to Listing 9.9, one more issue is worthy of note: the management of the lifecycle of the companion object.

Although the garbage collector manages Java’s memory, native memory usually must be allocated and deallocated explicitly. An AcmeProximitySensor object allocates its companion in its “open” method. So how does it free it? There are several possible answers to that question.

The first and best is “explicitly.” For reasons that will be discussed momentarily, the most effective way to handle explicitly managed memory is explicitly. Ideally, an object with a native peer that must be freed explicitly would be marked somehow so that clients would know that they should explicitly free it.

That is exactly the purpose of Java’s Closeable interface. An object that implements Closeable is hinting to its user that it needs to be closed explicitly when the user is through with it. The AcmeProximitySensor implements Closeable’s sub-interface AutoCloseable and uses it to free its companion.

A second strategy is a finalizer. A Java finalizer is a method with the specific signature, protected void finalize() throws Throwable. If an object has a method with that signature, it is called by the Java runtime just before the garbage collector frees the object’s memory. This seems perfect: with one small method, when the AcmeProximitySensor goes away, so does its companion.

Unfortunately, however, there’s no such thing as a free lunch. Finalizers are quite difficult to get right and, even when correct, have problems. Correctness first.

There is no guarantee about the order in which objects are finalized after they become eligible for garbage collection. The example code in Listing 9.12 has several problems, not the least of which is that it may get a NullPointerException in its finalizer. There is no guarantee that the list referenced by objects has itself not already been finalized when the finalizer for an instance of BrokenFinalizer is run. Its contents might well have been finalized first!

Listing 9.12 Broken Finalizer: Don’t Do This!

Click here to view code image

public class BrokenFinalizer implements Closeable {
    @NonNull
    private final List<NativeObject> objects

    // ...
    
    @Override
    protected void finalize() throws Throwable {
        for (NativeObject obj: objects) { obj.close(); }
    }
}

In addition to being brittle and very difficult to code, finalizers have two other problems. The first is that they impose a considerable inefficiency on the garbage collector. Because a finalizer can do all kinds of weird stuff (including “resurrect” the object being garbage collected by storing a reference to it somewhere!), the garbage collector has to do checks that are not necessary for an object that does not have a finalizer. These checks slow the collector down, cause it to place a heavier burden on the application, and mean that the lag between last use and deallocation gets longer.

The second problem, though, hinted at in the last sentence, is even worse. Although Java promises that it will run the garbage collector before it runs out of memory, there is no way to predict how long an object that is eligible for collection will sit around in memory before Java needs space and schedules it for collection. Furthermore, Java cannot guarantee that all finalizers will be run before an application runs out of memory. Finalizers are run in a platform-dependent way: almost universally on a single Java thread. If an application allocates and then frees a hundred large objects every second, each of those objects is scheduled for finalization, and each finalization takes a half a second to complete, the application is doomed. An application with native companion objects can build up a considerable backlog of dead objects before a garbage collection takes place. Instead of being freed incrementally, all of those objects are put on the finalization queue suddenly and all at once.

Despite these problems, finalizers can be a reasonable part of a “belt and suspenders” policy, as shown in Listing 9.9. An AcmeProximitySensor is Closeable: Client code is expected to explicitly close each instance when it is done with it. If the client code fails to do so, however, the finalizer will prevent a native memory leak.

The Native Shim: Reference Queues

The last and most complex way of managing native object lifecycles are reference queues. In return for somewhat more complicated code, reference queues remove many of the problems that finalizers have. They do not interfere with garbage collection, and they allow ordered freeing of objects.

As of Java 9, finalizers have officially been deprecated in favor of Cleaners. As part of Java 9, Cleaners are not available in Android. There is good news, though: PhantomReferences and ReferenceQueues, the technologies underlying Java 9’s Cleaner, are available in Android. The message to Android developers should be clear, even if Cleaners themselves are not available in the Android runtime environment.

The combination of a reference queue and a phantom reference works like this: The constructor for an instance of the PhantomReference class (or one of its subclasses) takes two arguments: an object and a reference queue. When the object whose reference is the first parameter to the constructor becomes eligible for garbage collection, the phantom reference (itself) is enqueued on the reference queue that was the second parameter to the constructor.

Calls to PhantomReference.get always return null: The referenced object itself is unreachable via the phantom reference and the existence of the reference cannot affect its reachability. What the reference can do, though, is provide a way to remember that there is unfinished business, when the object to which it is a reference no longer exists.

The implementation of a reference queue solution is somewhat difficult. Let’s take it in four parts. First, Listing 9.13 is the machinery that manages the lifecycle of an AcmeProximitySensor object and its peer.

Listing 9.13 Reference Queue: Native Companion and Its Lifecycle

Click here to view code image

public class AcmeProximitySensor implements AutoCloseable {

    // ...

    static final Map<AtomicLong, Reference<?>> CLEANERS = new HashMap<>();

    static { System.loadLibrary("acmeproximityjni"); }

    // ...

    @NonNull
    public static AcmeProximitySensor getSensor() {
        synchronized (CLEANERS) {
            final AtomicLong peerRef = new AtomicLong(open());
            final AcmeProximitySensor sensor = new AcmeProximitySensor(peerRef);
            CLEANERS.put(peerRef, new SensorCleaner(peerRef, sensor));
            return sensor;
        }
    }

    static void cleanup(AtomicLong peerRef) {
        final long peer = peerRef.getAndSet(0);
        if (peer == 0) { return; }

        synchronized (CLEANERS) {
            CLEANERS.remove(peerRef);
            close(peer);
        }
    }

    // ...

    @GuardedBy("CLEANERS")
    private static native void close(long handle);

    @GuardedBy("CLEANERS")
    private static native long open();

    @GuardedBy("CLEANERS")
    private static native int poll(long handle, int precision);
}

The static method getSensor is the factory method for instances of the class AcmeProximitySensor. Client code will call this method instead of the class constructor to create new instances. The class constructor is private, ensuring that this is the only way to create new instances: All new instances come from this method.

The method does four things:

1. It creates the native companion object and stashes the reference to it in an AtomicLong.

2. It creates the Java instance, passing the peer reference. The Java object now has access to its native peer.

3. It creates a SensorCleaner. This is the object that will be responsible for cleaning up the native peer if the user fails to do so.

4. It stores the SensorCleaner in a map.

The last step is important and yet easy to forget. Like any other Java object, the SensorCleaner is eligible for garbage collection as soon as there are no more references to it. Unless something, somewhere, remembers it, it will be garbage collected and will not be around to clean up after the AcmeProximitySensor instance with which it is associated.

The static method cleanup(AtomicLong) is the bottleneck at the end of the lifecycle of every AcmeProximitySensor instance. It simply undoes what the getSensor method did: It frees the native companion object and removes the SensorCleaner from the map so that it can be garbage collected.

It also ensures that the native close method will not be called more than once. The getAndSet in its first line ensures that the rest of the method will be executed no more than once for a given native peer, no matter how often it is called. The method is idempotent.

These two methods are the bookends for the AcmeProximitySensor lifecycle. The getSensor method is the only way to get one. All we have to do is make sure that the cleanup(AtomicLong) method is called at least once for every native companion.

As mentioned earlier, the best way to do this is explicitly. Listing 9.14 shows the implementation of the AcmeProximitySensor and, in particular, its implementation of the AutoCloseable interface.

Listing 9.14 Reference Queue: Explicit Close

Click here to view code image

public class AcmeProximitySensor implements AutoCloseable {

    // ...

    private final AtomicLong peerRef;

    private AcmeProximitySensor(AtomicLong peerRef) { this.peerRef = peerRef; }

    public int poll(int precision) throws IOException {
        synchronized (CLEANERS) {
            final long peer = peerRef.get();
            if (peer == 0) { throw new IOException("Device not open"); }
            return poll(peer, precision);
        }
    }

    @Override
    public void close() { cleanup(peerRef); }

    // ...
}

This code is similar to the equivalent code in Listing 9.9. The only significant difference, really, is that it delegates the call to close, required by the AutoCloseable interface, to cleanup(AtomicLong). Well-behaved client code will fulfill the outstanding condition: at least one call to cleanup(AtomicLong) via AcmeProximitySensor.close.

What happens, though, when client code is not well behaved? Listing 9.15 shows the backstop.

Listing 9.15 Reference Queue: Service Task

Click here to view code image

public class AcmeProximitySensor implements Closeable {
    private static final class SensorCleaner
        extends PhantomReference<AcmeProximitySensor> {
        private final AtomicLong peerRef;

        SensorCleaner(AtomicLong peerRef, AcmeProximitySensor sensor) {
            super(sensor, REF_QUEUE);
            this.peerRef = peerRef;
        }

        void cleanup() { AcmeProximitySensor.cleanup(peerRef); }
    }

    static final ReferenceQueue<AcmeProximitySensor> REF_QUEUE
        = new ReferenceQueue<>();

    @NonNull
    public static ScheduledTask getScheduledTask() {
        return new ScheduledTask(AcmeProximitySensor::cleanup, 100);
    }

    private static void cleanup() {
        Reference<? extends AcmeProximitySensor> ref;
        while ((ref = REF_QUEUE.poll()) instanceof SensorCleaner) {
              ((SensorCleaner) ref).cleanup();
        }
    }

    // ...
}

The two functions in Listing 9.15, getScheduledTask and cleanup(), manage the native companions objects left behind by ill-behaved clients. They also illustrate the biggest downside of using reference queues: scheduling cleanup.

Typically, finalizers are run on a special thread, maintained by the runtime, whose sole purpose is running finalizers. The finalizer thread receives notification for objects that need finalization and schedules their finalizer methods.

When using reference queues, however, scheduling object cleanup is not handled by the runtime. The application must poll the reference queue occasionally and schedule any work that it finds there.

There are good and bad aspects of this requirement. The bad parts are probably obvious: An application that uses reference queues must be able to schedule a job to service the reference queue, and it must be able to schedule any work that the job finds on a robust execution service. If the execution service fails for any reason, managed objects will no longer be freed correctly. That is likely to be disastrous.

Note, by the way, that reference queues do not change the indeterminate scheduling of object cleanup. Objects are only enqueued for cleanup when the garbage collector needs space and only processed when the application program gets around to scheduling a cleanup task.

The good aspects may be a little less apparent. Consider: Finalizers are problematic because it is possible to overwhelm the finalizer thread. As noted previously, freeing hundreds of finalizable objects quickly might very well add those objects to the finalizer’s queue faster than it can take them off for processing. Because the finalizer’s queue is difficult to access programmatically, little opportunity exists for an application to gauge whether or not its doom is impending.

Using a reference queue, however, the application controls the cleanup mechanism; it can scale the object recovery process to the need. A multi-threaded, high-priority execution service might be able to stay ahead of object allocation.

Better yet, though, suppose that the same thread processes both the application-specific tasks that cause memory allocation and the reference queue that cleans them up. If the thread is busy managing the reference queue, it cannot allocate new objects. Allocation is naturally limited to creating no more than it can free. Governing the object allocation rate in this way makes for extremely robust apps.

Listing 9.15 posits a scheduling mechanism elsewhere in the system that registers new periodic tasks by calling a class’s getScheduledTask method. The method returns the task to be run and the interval (in milliseconds) between runs. Surely, many other ways exist for accomplishing something similar: This particular implementation simply illustrates that the method cleanup() must be called periodically.

The cleanup() method polls the reference queue and calls the cleanup(AtomicLong) for each instance of the SensorCleaner object (whose associated AcmeProximitySensor has now been garbage collected) that it finds there. Recall from Listing 9.13 that each AcmeProximitySensor had a SensorCleaner associated with it in the factory method getSensor. This is the guarantee that, even if client code fails to close the sensor object, the cleanup(AtomicLong) will be called to free the native companion object.

There are a couple subtleties to be aware of. First, note that it is important that there are several references to the AtomicLong that contain the handle to the native peer. If the AcmeProximitySensor held the only reference, then when it became unreachable, the AtomicLong might be freed even before the sensor object itself. The SensorCleaner cannot depend on being able to find the native object unless it itself keeps a reference.

Second, notice that when a well-behaved client explicitly closes a sensor object, its SensorCleaner is removed from the map! That means the cleaner object is now unreachable and that the AcmeProximitySensor object holds the only reachable reference to the peer handle. It is entirely possible that the cleaner will be garbage collected first; thus, it will never be queued or scheduled. That’s perfectly okay because there’s nothing left for it to do.

Because the AtomicLong that is the reference to the native peer is in the map, a SensorCleaner is guaranteed that it will have access to it when the cleaner runs and that either it is the first attempt to free the native companion or that it will not try to do so.

Don’t Break the Rules

It is entirely possible to break Java’s rules using native code. For instance, using native code, it is relatively easy to change the content of String or, indeed, any immutable object. Although JNI methods make some attempt to enforce visibility (public versus private) and mutability (final) constraints, sidestepping nearly any of them is quite possible. Java developers are used to being able to make assumptions about the environment in which their code runs. Changing the rules is asking for trouble.

Clearly and Without Exception, Document Native References to Java Code

Always and without exception, document any native use of Java code. If a native method refers to a class member by name, document that reference in a comment on the field. If native code calls a Java method, be certain that the Java method has a comment that indicates the fact. The same goes for native code that creates new instances of some Java class or other. As a related suggestion, be sure that any code that looks up Java identifiers—fields, classes, or methods—fails immediately and clearly if it cannot find its target. Failure to do these things will lead to bizarre crashes when some well-meaning developer does some small refactor.

Pass Simple Types to Native Code

The rest of the hints in this chapter have a single theme: When possible, don’t put the burden of dealing with Java constructs on native code. Whenever possible, Java code should deal with Java data structures and should communicate with native code using only primitive types, Strings and arrays of those types. This may mean violating other general rules. For instance, passing the information in a complex data structure to its native companion as primitive types may mean that the native method has an uncomfortably large number of arguments. That is the lesser evil. Somewhere, code will have to extract the information. Keep that code on the Java side.

Make Native Methods Static, When Convenient

This tip is more a corollary to the previous hint than a new suggestion. Native instance methods are passed references to the calling Java instance. Cases surely exist in which that may be useful. In general, though, avoiding it is best. Pass the data that the native method requires and pass it to a static method instead of passing the whole object to an instance method.

Beware the Garbage Collector

This is probably the most important and most easily forgotten of the hints. Remember that as your native code runs, the garbage collector daemon is also running. It may move data to which you have a native pointer. Worse yet, it might deallocate it.

To keep the garbage collector from freeing an object, the object must appear to the collector as “reachable”: There must be some way that running Java code can obtain a reference to it. Consider, however, a Java object that is created by native code. There are no references anywhere in the Java environment to this new object. Because there are no references, it is eligible for immediate garbage collection! The JNI provides two solutions to this problem: the LocalRef and the GlobalRef.

A LocalRef behaves as if a reference to an object had been put into the call stack of the nearest (in the stack) calling Java method. It creates a reference to the object that is visible to the garbage collector, making it reachable and thus ineligible for deallocation.

Many JNI methods that return references to Java objects also create a LocalRef to the returned object (be sure to verify this for specific calls). In general, if there is the potential for an object to disappear while native code is using it, a JNI call that returns a reference will create a LocalRef for it. Parameters to JNI method calls have LocalRefs as well. There is no danger that an object passed to a native method through the JNI will suddenly vanish.

LocalRefs are managed. They are automatically deleted (popped off the stack) when a native method returns to its Java language caller. Unfortunately, however, implementations of the JNI support only a limited number of LocalRefs: typically a few hundred but perhaps only a handful. As a rule of thumb, immediately deleting a LocalRef when it is no longer needed is best practice.

In fact, several circumstances exist under which deleting them explicitly is absolutely essential. Consider the example in Listing 9.16: native code that creates new objects of some kind and then adds them to a Java array.

Listing 9.16 Filling an Array

Click here to view code image

jobjectArray ds = env->NewObjectArray(arraySize, klass_MyObject, nullptr);
for (int i = 0; i < arraySize; i++) {
    jobject d = createNewObject(env, array[i]);
    env->SetObjectArrayElement(ds, i, d);
    env->DeleteLocalRef(d);
 }

The JNI creates a LocalRef for the array created in the first line of the code. It also creates a LocalRef for each new object to be inserted into the array. After a new object is inserted into the array, it is reachable via the array. The individual LocalRefs for the new objects can (and should) be deleted. If the array is large, it is entirely possible that failing to delete the LocalRefs will exhaust the local ref pool.

Another, somewhat trickier condition is one in which the calling code never returns to a Java method. This can happen when a native thread, for instance, calls into Java code. Imagine, for example, a native thread—perhaps a thread servicing network connections—that uses a Java logger. The native code might create a Java String, log it, and then go back about its business. The LocalRef to the String will never be released because the calling code never returns to a Java caller.

The second kind of reference in the JNI toolbox is a GlobalRef. GlobalRefs are the way that native code holds a reference to a Java object across call boundaries. A GlobalRef behaves as if a reference to the object to which it refers had been added to a permanent static array. The ref prevents the garbage collector from recovering the referenced object’s memory until the reference is deleted explicitly. Native developers, who are used to explicit memory management, will find this completely normal.

A common example of the need of a GlobalRef is native creation of a Java object, as shown in Listing 9.17.

Listing 9.17 Native Object Creation

Click here to view code image

jclass klass_MyObject = env->FindClass(“my/project/MyObject”);
if (!localClass)
    return nullptr;

method_MyObject_ctor = env->GetMethodID(
    klass_MyObject,
    “<init>”,
    “(I)V”);
if (!method_MyObject_ctor)
    return nullptr;

return env->NewObject(klass_MyObject, method_MyObject_ctor, (jint) param1);

If this call is used frequently, optimizing it might be possible. Both klass_MyObject and method_MyObject_ctor are references to Java objects: the class named “MyObject” and a constructor in that class with a single integer parameter, respectively. Using JNI methods to look up those references for every call to this code will take a substantial proportion of its execution time. To optimize it, an initialization method might be to look up the two references once and then hold them. Such an optimization requires a GlobalRef for each.

Use GlobalRefs with care. Although the limit on the number available (typically 65535) is usually much larger than the limit on the number of LocalRefs, they are memory leaks. Treat them as you would any other unmanaged memory.

Note that neither a LocalRef nor GlobalRef affects the garbage collector’s ability to move an object in memory. Although such movement is completely invisible from Java code, a native reference can become a pointer to garbage, quite literally, in the middle of a line of code. This is not a tolerable situation and JNI calls have two strategies for handling it: copying and pinning. When using JNI methods that allow access the contents of a Java object—as with methods that created implicit LocalRefs—be sure to verify which of these two strategies a specific call uses.

Copying is just what it sounds like: An atomic JNI call copies the contents of a Java object into native-managed memory. The native code is free to do anything it likes with the copy, including, at some point, atomically copying it back into the Java object.

When an object is pinned, on the other hand, the garbage collector is not allowed to move it. Native code can access the contents of the pinned object directly, perhaps without the overhead of the copy. Pinning an object, however, means that memory in the Java heap is no longer under the control of the garbage collector. This can easily lead to fragmentation and premature out-of-memory errors. Best practice is to pin objects only if necessary, and then for as short a time as possible.

Use Weak Refs When Native Code Must Hold a Reference to a Java Object

A significant portion of this chapter is devoted to the discussion of how a Java object can hold a reference to a native companion object. What happens, though, when a native object needs to be able to find a particular Java object?

Consider, for instance, a native network management library. Suppose that client code creates a new Java Connection object for each of several network connections. The Connection object in turn creates a native companion object that actually handles socket connections. Finally, suppose that the native object calls back into Java code for each of the various events in the connection lifecycle.

Clearly, the callbacks from the native companion object must be calls to the specific Java Connection instance that created it and not to any other instance. The native code must, therefore, hold a reference to its Java companion.

This is, certainly, possible. As we’ve just seen, the native companion object might hold a GlobalRef to its Java companion: the Java code now has a reference to the native object and the native object has a reference to the Java object.

The problem with this, of course, is that a GlobalRef to the Java object will make it ineligible for garbage collection. Unless there is some explicit means of freeing it (and that explicit mechanism is carefully used for every instance), its referent will never be freed, will never be finalized (or added to a reference queue), and will never free its native companion. The belt still works but the suspenders are gone. Unless a clear architectural reason exists for doing the aforementioned, a good practice is to leave the management of native objects to their Java companions, not vice versa.

There are two ways around this issue. The first is a special global reference, a WeakGlobalRef. A WeakGlobalRef is similar to a GlobalRef, except that (like a Java WeakReference) it does not prevent the garbage collection of the Java object to which it refers. It is different from a raw native reference in that it will never point at garbage: It will always either point at the intended object or be null.

It is important to note that the referent in a WeakGlobalRef can disappear at any time, even between two native instructions, causing intermittent failures. Listing 9.18 illustrates such a scenario: a snippet in which a native instance stores a reference to its Java companion.

Listing 9.18 Incorrect Use of a WeakRef: Don’t Do This!

Click here to view code image

mCompanion = reinterpret_cast<jobject>(env->NewWeakGlobalRef(javaObj));
if (env->isSameObject(mCompanion, NULL) 
    return;
jclass klass = env->getObjectClass(mCompanion) // mCompanion may be NULL!
// ...

Fortunately, a WeakGlobalRef can be used as the argument to LocalRef (or a GlobalRef). Local and global refs protect their referents from garbage collection. Listing 9.19 illustrates a corrected version of Listing 9.18.

Listing 9.19 Obtain a LocalRef from a WeakGlobalRef

Click here to view code image

mCompanion = reinterpret_cast<jobject>(env->NewWeakGlobalRef(javaObj));
companion = reinterpret_cast<jobject>(env->NewLocalRef(mCompanion));
if (env->isSameObject(companion, NULL) 
    return;
jclass klass = env->getObjectClass(companion) // safe!
// ...

There is one other way of managing native handles in Java objects. In this architecture, references to Java objects are never passed to native code at all. Instead, they are kept as weak references in a map at the Java/native boundary. Think of it as a “hat check”: Java hands native code a token, which can be redeemed for a Java object. The token, however, is completely opaque to the native code. Listing 9.20 shows a sample implementation.

Listing 9.20 Native Reference “Hat Check”

Click here to view code image

public class NativeRef<T> {
    @NonNull
    @GuardedBy("this")
    private final Random rnd = new Random();

    @NonNull
    @GuardedBy("this")
    private final Map<Integer, WeakReference<T>> refs = new HashMap<>();

    public synchronized int bind(@NonNull T obj) {
        int ref;
        do { ref = rnd.nextInt(Integer.MAX_VALUE); }
        while (refs.containsKey(ref));
        refs.put(ref, new WeakReference<>(obj));
        return ref;
    }

    public synchronized void unbind(int key) { refs.remove(key); }

    @Nullable
    public synchronized T getObjFromContext(long lref) {
        if ((lref < 0) || (lref > Integer.MAX_VALUE)) {
            throw new IllegalArgumentException("Ref out of bounds: " + lref);
        }

        final Integer key = (int) lref;
        final WeakReference<T> ref = refs.get(key);
        if (ref == null) { return null; }

        final T obj = ref.get();
        if (obj == null) { refs.remove(key); }
        return obj;
    }
}

This architecture has many of the same features that made WeakGlobalReferences attractive. Because the reference map holds weak references, native objects cannot force their Java companions to stay in memory. Perhaps an advantage, this architecture does not use the size-limited LocalRef pool.

Note that the implementation uses only positive integers for tokens. For most applications, this provides plenty of space and avoids problems that arise from sign extension.