How do I debug Fennel JNI handles?
Farrago maintains handles to Fennel C++ objects of various types, including the Fennel Database class, transactions, and stream graphs. Handles are effectively C++ pointers converted to long integers. Fennel maintains a count of currently allocated handles and Farrago tests that this count is zero when it shuts down (see method net.sf.farrago.db.FarragoDatabase.assertNoFennelHandles).
When the Fennel handle count assertion fails, it indicates a resource leak of some kind. Determining which resource can be difficult. Fennel can be configured to log the allocation and deallocation of JNI handles to a file. To enable this, start Farrago and execute:
alter system set "jniHandleTraceFile" = '/tmp/some/path'
After restarting Farrago, all JNI handle information will be logged to /tmp/some/path. Setting the path to disables the tracing (after restarting Farrago).
The checkJniHandleTrace script (found in the Eigenbase Perforce server under open/util/bin) will analyze the trace file and generate a list of missing deallocations including the object's type and memory location. This is often enough to determine the cause of the problem.
It may be necessary to configure Fennel tracing to output pointer information to correlate the JNI handle trace data with specific actions taken by the user.
The script also detects other conditions, such as the same handle being counted twice or handles being flagged as deallocated despite never having been flagged as allocated.
Because Farrago's ant test completely rebuilds the Farrago catalog and because Farrago unit tests restore startup parameters after each test, you can define a special property to cause the necessary database startup parameter to be configured during catalog creation:
ant test -Dtrace.fennel.handles=/some/path/fennel.handles
A file named /some/path/fennel.handles will be generated with traces across all Farrago invocations that occur during ant test. Setting this property also works when executing just ant createCatalog. Instead of using the command line, the property may also be set in the customBuild.properties file. In any event, remember to rebuild the catalog without the fennel.trace.handles property to disable handle tracing in your backed up Farrago catalog. Otherwise, ant restoreCatalog will re-enable tracing.