[sl@eng 97/07/24]

All the free-standing functions (those that are not JNI native

methods) must not leak local references.  Local references are

automatically freed when the native method returns to Java. However,

the free-standing functions are called from the event loop that never

returns to Java. If these functions do not clean up the local

references they create, the Java objects corresponding to the local

references will never be garbage collected.

This is caused by the fact that JNI does not clean up local refs 

until control returns to Java. However, this problem is somewhat

unique to AWT code because AWT code has long-running native methods

that never return.

Local refs may be cleaned up manually *before* control returns to 

Java in one of the following two ways:

1. Use EnsureLocalCapacity at the beginning of the function to make

sure the VM has enough memory to create the number of JNI local refs

needed in the function. Use DeleteLocalRef to clean up any local ref

created inside the function that are not returned as the result. For

example:

  void AwtComponent::MeasureListItem(JNIEnv *env, 

				     MEASUREITEMSTRUCT far& measureInfo)

  {

      if (env->EnsureLocalCapacity(1) < 0) {

	  return;

      }

      jobject dimension = PreferredItemSize(env);

      ... /* Use dimension */

      env->DeleteLocalRef(dimension);

  }

2. Use PushLocalFrame and PopLocalFrame to start a new local reference

frame. All the local refs created in the new frame will be automatically

freed when PopLocalFrame is called. For example, the above function can be

rewritten as follows:

  void AwtComponent::MeasureListItem(JNIEnv *env, 

				     MEASUREITEMSTRUCT far& measureInfo)

  {

      if (env->PushLocalFrame(1) < 0) {

	  return;

      }

      jobject dimension = PreferredItemSize(env);

      ... /* Use dimension */

      env->PopLocalFrame(NULL);

  }

The second approach is easier to use when there are multiple local refs 

to manage. The first approach is more efficient when the function only 

needs to create a small number (3 or less) of local refs.

Pay special attention to local refs created inside a loop. They must be

deleted after every iteration, otherwise they accumulate very quickly:

int AwtFont::getFontDescriptorNumber(JNIEnv *env, jobject font,

				     jobject fontDescriptor)

{

    ... /* other stuff */

    jarray array = ...

    for (i = 0; i < num; i++){

	refFontDescriptor = env->GetObjectArrayElement(array, i);

	if (env->IsSameObject(refFontDescriptor, fontDescriptor)) {

	    env->DeleteLocalRef(refFontDescriptor);

	    env->DeleteLocalRef(array);

	    return i;

	}

	env->DeleteLocalRef(refFontDescriptor);

    }

    env->DeleteLocalRef(array);

    return 0;	// Not found.  Use default.

}

Note that we must make sure the local refs are cleaned up at every possible

return branch. To reduce code duplication, many AWT functions use "goto"

to jump to a common set of cleanup statements.

Even if we use PushLocalFrame, we must still delete the local refs created

in the loop:

    if (env->PushLocalFrame(2) < 0)

	return 0;

    jarray array = ...

    for (i = 0; i < num; i++){

	refFontDescriptor = env->GetObjectArrayElement(array, i);

	if (env->IsSameObject(refFontDescriptor, fontDescriptor)) {

	    env->PopLocalFrame(NULL);

	    return i;

	}

	env->DeleteLocalRef(refFontDescriptor);

    }

    env->PopLocalFrame(NULL);

    return 0;	// Not found.  Use default.

unless we ensure that we have space for all possible local refs we are 

going to create inside the loop (note the different argument passed 

to PushLocalFrame):

// Maximum number of local refs we can create in this code segment is

// num + 1.

    if (env->PushLocalFrame(num + 1) < 0)

	return 0;

    jarray array = ...

    for (i = 0; i < num; i++){

	refFontDescriptor = env->GetObjectArrayElement(array, i);

	if (env->IsSameObject(refFontDescriptor, fontDescriptor)) {

	    env->PopLocalFrame(NULL);

	    return i;

	}

// no longer necessary. env->DeleteLocalRef(refFontDescriptor);

    }

    env->PopLocalFrame(NULL);

    return 0;	// Not found.  Use default.

THINGS TO DO:

    1. Investigate another possibility of dealing with local refs. Instead

    of making sure every free-standing function does not leak local refs,

    we could alternatively create a new local ref frame for each invocation

    of callback functions. All local refs created during the execution of 

    the callback will then be automatically freed.

    2. Handle exceptions properly. The current code lacks error checking

    and recovery. This leads to random runtime crashes.