svn commit: r1859042 - /uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.migration.aids.xml

[sc...@apache.org]

Author: schor
Date: Thu May  9 21:16:14 2019
New Revision: 1859042

URL: http://svn.apache.org/viewvc?rev=1859042&view=rev
Log:
[UIMA-6043] document report of pinning, also fix typo

Modified:
    uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.migration.aids.xml

Modified: uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.migration.aids.xml
URL: http://svn.apache.org/viewvc/uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.migration.aids.xml?rev=1859042&r1=1859041&r2=1859042&view=diff
==============================================================================
--- uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.migration.aids.xml (original)
+++ uima/uv3/uimaj-v3/trunk/uima-docbook-v3-users-guide/src/docbook/uv3.migration.aids.xml Thu May  9 21:16:14 2019
@@ -134,7 +134,7 @@ under the License.
          <row>
            <entry><para>Disabling runtime feature validation</para></entry>
            
-           <entry><para><code>uima.uima.disable_runtime_feature_validation</code></para>
+           <entry><para><code>uima.disable_runtime_feature_validation</code></para>
            
                   <para>Once code is running correctly, you may remove this check for performance
                     reasons by setting this property.</para></entry>
@@ -150,6 +150,33 @@ under the License.
                     reasons by setting this property.</para></entry>
          </row>
 
+         <!-- ******************************************************************************* -->
+         <row>
+           <entry spanname="fullwidth"><emphasis role="bold">Reporting</emphasis></entry>
+         </row>
+         
+         <row>
+           <entry><para>Report feature structure pinning</para></entry>
+           <entry><para><code>uima.report.fs.pinning="nnn"</code></para>
+           
+              
+              <para>Default: not enabled; nnn is the maximum number of reports to produce.  If nnn is 
+              omitted, it defaults to 10.</para>
+
+              <para>When enabled, this flag will cause reports to System.out with call traces for the first nnn
+                    instances of actions which lead to pinning Feature Structures in memory.</para>
+              <para>Typically, this should not happen, and no-longer-reachable Feature Structures are 
+                    garbage collected.</para>
+              <para>But some operations (such as using the CAS low level APIs, which return
+                    integer handles representing Feature Structures) pin the Feature Structures, in case 
+                    code in the future uses those integer handles to access the Feature Structure.</para>
+                    
+              <para>It is recommended that code be improved over time to use JCas access methods, instead of low-level
+                    CAS APIs, to avoid pinning unreachable Feature Structures.  This report enables finding
+                    those parts of the code that are pinning Feature Structures.</para>
+           </entry>       
+         </row>
+
        </tbody>
      </tgroup>
    </informaltable>