<commit_before><html>
<!--
  -->

<head>
<title>Farrago Developer FAQ</title>
<link rel="stylesheet" href="stylesheet.css" type="text/css" />
<style>
<!--
.small { font-family: verdana,arial,helvetica,sans-serif; font-size: x-small; }
-->
</style>
</head>

<body>
<h1>Farrago Developer FAQ</h1>

<hr>

<h2>How do I get a Java stack trace?</h2> 

Some front-end tools allow you to see Java stack traces directly.  For
example, in sqlline, if you issue the <code>!set verbose on</code>
command, a stack trace is reported with every subsequent error.

<p>

For other cases, you can often make use of the fact that all
exceptions propagated through the Farrago JDBC driver are traced.  In
file <code>dev/farrago/trace/FarragoTrace.properties</code>, set
<code>net.sf.farrago.jdbc.level=FINER</code>, then do whatever causes
the exception and look at the tail of file 
<code>dev/farrago/trace/FarragoTrace.log</code>.

<hr>

<h2>How do I get a Fennel C++ stack trace?  How do I debug Fennel
when it's called from Java?</h2> 

At the moment, there's no nice automated stack trace like in Java
(besides a standard core dump).  However, it is possible to use gdb to
debug Fennel.  Before starting the Java virtual machine, set
environment variable <code>FENNEL_JNI_DEBUG=1</code> in the shell from
which you are going to run Java.  When the Fennel JNI layer is loaded,
you should see a message like "Waiting for debugger; pid=18454".
Start gdb and tell it to attach to the process with the given pid.
The process should be sleeping in method <code>JNI_OnLoad</code>; set
whatever breakpoints you want and then issue the gdb continue command
(see below).  Unfortunately, gdb receives many spurious signals when
attached to the Java Virtual Machine (at least on Linux, even
SIGSEGV!)  The only choices are to tell gdb to ignore them (e.g. with
the command <code>handle SIGSEGV ignore</code>), or to manually
continue past them each time (like if you want to track down a
<b>real</b> segfault).

<p>On some systems (e.g., Fedora Core 2, but it probably depends on
the version of gdb), the gdb continue command will not cause the call
to <code>sleep()</code> to end prematurely.  In this case, set
<code>FENNEL_JNI_DEBUG=2</code> and use the gdb command <code>signal
SIGHUP</code> or <code>signal 1</code> to end the call to
<code>pause()</code> in <code>JNI_OnLoad</code>.

<hr>

<h2>How do debug Fennel JNI Handles?</h2>

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
<code>net.sf.farrago.db.FarragoDatabase.assertNoFennelHandles()</code>).

<p>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:

<pre><code>alter system set "jniHandleTraceFile" = '/tmp/some/path'</code></pre>
<commit_msg>FARRAGO:  fix typo in faqTech.html<commit_after><html>
<!--
  -->

<head>
<title>Farrago Developer FAQ</title>
<link rel="stylesheet" href="stylesheet.css" type="text/css" />
<style>
<!--
.small { font-family: verdana,arial,helvetica,sans-serif; font-size: x-small; }
-->
</style>
</head>

<body>
<h1>Farrago Developer FAQ</h1>

<hr>

<h2>How do I get a Java stack trace?</h2> 

Some front-end tools allow you to see Java stack traces directly.  For
example, in sqlline, if you issue the <code>!set verbose on</code>
command, a stack trace is reported with every subsequent error.

<p>

For other cases, you can often make use of the fact that all
exceptions propagated through the Farrago JDBC driver are traced.  In
file <code>dev/farrago/trace/FarragoTrace.properties</code>, set
<code>net.sf.farrago.jdbc.level=FINER</code>, then do whatever causes
the exception and look at the tail of file 
<code>dev/farrago/trace/FarragoTrace.log</code>.

<hr>

<h2>How do I get a Fennel C++ stack trace?  How do I debug Fennel
when it's called from Java?</h2> 

At the moment, there's no nice automated stack trace like in Java
(besides a standard core dump).  However, it is possible to use gdb to
debug Fennel.  Before starting the Java virtual machine, set
environment variable <code>FENNEL_JNI_DEBUG=1</code> in the shell from
which you are going to run Java.  When the Fennel JNI layer is loaded,
you should see a message like "Waiting for debugger; pid=18454".
Start gdb and tell it to attach to the process with the given pid.
The process should be sleeping in method <code>JNI_OnLoad</code>; set
whatever breakpoints you want and then issue the gdb continue command
(see below).  Unfortunately, gdb receives many spurious signals when
attached to the Java Virtual Machine (at least on Linux, even
SIGSEGV!)  The only choices are to tell gdb to ignore them (e.g. with
the command <code>handle SIGSEGV ignore</code>), or to manually
continue past them each time (like if you want to track down a
<b>real</b> segfault).

<p>On some systems (e.g., Fedora Core 2, but it probably depends on
the version of gdb), the gdb continue command will not cause the call
to <code>sleep()</code> to end prematurely.  In this case, set
<code>FENNEL_JNI_DEBUG=2</code> and use the gdb command <code>signal
SIGHUP</code> or <code>signal 1</code> to end the call to
<code>pause()</code> in <code>JNI_OnLoad</code>.

<hr>

<h2>How do I debug Fennel JNI Handles?</h2>

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
<code>net.sf.farrago.db.FarragoDatabase.assertNoFennelHandles()</code>).

<p>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:

<pre><code>alter system set "jniHandleTraceFile" = '/tmp/some/path'</code></pre>

{'fraction_non_alphanumeric': 0.09289188765102778, 'fraction_numerical': 0.0053350070610387575, 'mean_word_length': 4.630742049469965, 'pattern_counts': {'":': 0, '<': 121, '<?xml version=': 0, '>': 121, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3360956', 'n_tokens_mistral': 2050, 'n_tokens_neox': 1953, 'n_words': 881}