[kaffe] CVS kaffe (guilhem): New FAQ for local references.

[Kaffe CVS]

PatchSet 5659 
Date: 2005/04/04 11:06:48
Author: guilhem
Branch: HEAD
Tag: (none) 
Log:
New FAQ for local references.

Members: 
	ChangeLog:1.3829->1.3830 
	FAQ/FAQ.references:INITIAL->1.1 

Index: kaffe/ChangeLog
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>
 
 	* config/Makefile.am:
===================================================================
Checking out kaffe/FAQ/FAQ.references
RCS:  /home/cvs/kaffe/kaffe/FAQ/FAQ.references,v
VERS: 1.1
***************
--- /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
+referenced object.
+
+More information about VM references can be found at:
+
+     http://java.sun.com/j2se/1.4.2/docs/guide/jni/spec/design.html#wp1242
+     http://java.sun.com/j2se/1.4.2/docs/guide/jni/jni-12.html#localrefs 
+
+
+Guilhem Lavaux <guilhem at kaffe.org>
+April 4, 2005