1[sl@eng 97/07/24]
2
3All the free-standing functions (those that are not JNI native
4methods) must not leak local references.  Local references are
5automatically freed when the native method returns to Java. However,
6the free-standing functions are called from the event loop that never
7returns to Java. If these functions do not clean up the local
8references they create, the Java objects corresponding to the local
9references will never be garbage collected.
10
11This is caused by the fact that JNI does not clean up local refs 
12until control returns to Java. However, this problem is somewhat
13unique to AWT code because AWT code has long-running native methods
14that never return.
15
16Local refs may be cleaned up manually *before* control returns to 
17Java in one of the following two ways:
18
191. Use EnsureLocalCapacity at the beginning of the function to make
20sure the VM has enough memory to create the number of JNI local refs
21needed in the function. Use DeleteLocalRef to clean up any local ref
22created inside the function that are not returned as the result. For
23example:
24
25  void AwtComponent::MeasureListItem(JNIEnv *env, 
26				     MEASUREITEMSTRUCT far& measureInfo)
27  {
28      if (env->EnsureLocalCapacity(1) < 0) {
29	  return;
30      }
31      jobject dimension = PreferredItemSize(env);
32
33      ... /* Use dimension */
34
35      env->DeleteLocalRef(dimension);
36  }
37
382. Use PushLocalFrame and PopLocalFrame to start a new local reference
39frame. All the local refs created in the new frame will be automatically
40freed when PopLocalFrame is called. For example, the above function can be
41rewritten as follows:
42
43  void AwtComponent::MeasureListItem(JNIEnv *env, 
44				     MEASUREITEMSTRUCT far& measureInfo)
45  {
46      if (env->PushLocalFrame(1) < 0) {
47	  return;
48      }
49      jobject dimension = PreferredItemSize(env);
50
51      ... /* Use dimension */
52
53      env->PopLocalFrame(NULL);
54  }
55
56The second approach is easier to use when there are multiple local refs 
57to manage. The first approach is more efficient when the function only 
58needs to create a small number (3 or less) of local refs.
59
60Pay special attention to local refs created inside a loop. They must be
61deleted after every iteration, otherwise they accumulate very quickly:
62
63int AwtFont::getFontDescriptorNumber(JNIEnv *env, jobject font,
64				     jobject fontDescriptor)
65{
66    ... /* other stuff */
67
68    jarray array = ...
69
70    for (i = 0; i < num; i++){
71	refFontDescriptor = env->GetObjectArrayElement(array, i);
72	if (env->IsSameObject(refFontDescriptor, fontDescriptor)) {
73	    env->DeleteLocalRef(refFontDescriptor);
74	    env->DeleteLocalRef(array);
75	    return i;
76	}
77	env->DeleteLocalRef(refFontDescriptor);
78    }
79    env->DeleteLocalRef(array);
80    return 0;	// Not found.  Use default.
81}
82
83Note that we must make sure the local refs are cleaned up at every possible
84return branch. To reduce code duplication, many AWT functions use "goto"
85to jump to a common set of cleanup statements.
86
87Even if we use PushLocalFrame, we must still delete the local refs created
88in the loop:
89
90    if (env->PushLocalFrame(2) < 0)
91	return 0;
92    jarray array = ...
93    for (i = 0; i < num; i++){
94	refFontDescriptor = env->GetObjectArrayElement(array, i);
95	if (env->IsSameObject(refFontDescriptor, fontDescriptor)) {
96	    env->PopLocalFrame(NULL);
97	    return i;
98	}
99	env->DeleteLocalRef(refFontDescriptor);
100    }
101    env->PopLocalFrame(NULL);
102    return 0;	// Not found.  Use default.
103
104unless we ensure that we have space for all possible local refs we are 
105going to create inside the loop (note the different argument passed 
106to PushLocalFrame):
107
108// Maximum number of local refs we can create in this code segment is
109// num + 1.
110    if (env->PushLocalFrame(num + 1) < 0)
111	return 0;
112    jarray array = ...
113    for (i = 0; i < num; i++){
114	refFontDescriptor = env->GetObjectArrayElement(array, i);
115	if (env->IsSameObject(refFontDescriptor, fontDescriptor)) {
116	    env->PopLocalFrame(NULL);
117	    return i;
118	}
119// no longer necessary. env->DeleteLocalRef(refFontDescriptor);
120    }
121    env->PopLocalFrame(NULL);
122    return 0;	// Not found.  Use default.
123
124THINGS TO DO:
125
126    1. Investigate another possibility of dealing with local refs. Instead
127    of making sure every free-standing function does not leak local refs,
128    we could alternatively create a new local ref frame for each invocation
129    of callback functions. All local refs created during the execution of 
130    the callback will then be automatically freed.
131
132    2. Handle exceptions properly. The current code lacks error checking
133    and recovery. This leads to random runtime crashes.
134