[kaffe] CVS kaffe (guilhem): New FAQ for local references.
cvs-commits at kaffe.org
Mon Apr 4 04:11:24 PDT 2005
Date: 2005/04/04 11:06:48
New FAQ for local references.
diff -u kaffe/ChangeLog:1.3829 kaffe/ChangeLog:1.3830
--- kaffe/ChangeLog:1.3829 Mon Apr 4 00:07:30 2005
+++ kaffe/ChangeLog Mon Apr 4 11:06:48 2005
@@ -1,3 +1,7 @@
+2005-04-04 Guilhem Lavaux <guilhem at kaffe.org>,
+ * FAQ/FAQ.references: New file
2005-04-04 Dalibor Topic <robilad at kaffe.org>
Checking out kaffe/FAQ/FAQ.references
--- /dev/null Sun Aug 4 19:57:58 2002
+++ kaffe/FAQ/FAQ.references Mon Apr 4 11:11:24 2005
@@ -0,0 +1,57 @@
+FAQ about local references
+Why do I get "FATAL ERROR: No more room for local references" ?
+As a user, it is likely you must report this error to the original
+developers of the java application/library you are using.
+As a developer, it means that the native code has got too many object
+references from the VM without acknowledging the VM that it does not
+need anymore the object.
+Each time a reference is returned by the VM, it attaches a local
+reference to it to inform the garbage collector that it may not free
+this object until the reference has been cleared. Indeed the garbage
+collector will look at all local/global references, all java
+references and the content of the stack before taking the decision of
+freeing an object.
+These references has been historically introduced for object which are
+only referenced by the native code into some variables that are not
+stored on the stack.
+What can I do to solve this problem ?
+There are two different cases:
+(1) You are invoking the VM from a function invoked by the VM.
+Then all local references are freed at the exiting of the function
+invoked by the VM. Either you may need more room for references or,
+more likely, you may want to remove the references because the
+referenced objects are not used anymore or are anyway stored on the
+stack. In this case, you have to call the JNI function DeleteLocalRef
+with the object reference. The object will still be available. If you
+need more reference, you must call the JNI function
+EnsureLocalCapacity with the number of references you need.
+(2) You are invoking the VM from a function which has not been invoked
+ by the VM.
+This case looks like the previous one except for the following: the
+local reference table is never freed. So, you have to be really
+careful of deleting all local references. If you really need to keep
+an object into some global variable then you must invoke the JNI
+function NewGlobalRef to prevent the garbage collector to free the
+More information about VM references can be found at:
+Guilhem Lavaux <guilhem at kaffe.org>
+April 4, 2005
More information about the kaffe