You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by ap...@apache.org on 2006/11/29 00:23:50 UTC
svn commit: r480277 [6/7] - in /harmony/standard/site:
docs/subcomponents/drlvm/ docs/subcomponents/drlvm/images/
xdocs/subcomponents/drlvm/ xdocs/subcomponents/drlvm/images/
Added: harmony/standard/site/xdocs/subcomponents/drlvm/Jitrino_PMF.html
URL: http://svn.apache.org/viewvc/harmony/standard/site/xdocs/subcomponents/drlvm/Jitrino_PMF.html?view=auto&rev=480277
==============================================================================
--- harmony/standard/site/xdocs/subcomponents/drlvm/Jitrino_PMF.html (added)
+++ harmony/standard/site/xdocs/subcomponents/drlvm/Jitrino_PMF.html Tue Nov 28 15:23:47 2006
@@ -0,0 +1,2628 @@
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+ <meta http-equiv="Content-Type"
+ content="text/html; charset=us-ascii" />
+ <link rel="Stylesheet"
+ type="text/css"
+ href="site.css" />
+
+ <title>Jitrino Pipeline Management Framework</title>
+</head>
+
+<body>
+ <h1><a id="top"
+ name="top"></a>Jitrino Pipeline Management Framework</h1>
+
+ <p class="TOCHeading"><a href="#Revision_History">Revision
+ History</a></p>
+
+ <p class="TOCHeading"><a href="#About_This_Document">1. About
+ This Document</a></p>
+
+ <p class="TOC"><a href="#Purpose">1.1 Purpose</a></p>
+
+ <p class="TOC"><a href="#Intended_Audience">1.2 Intended
+ Audience</a></p>
+
+ <p class="TOC"><a href="#Documentation_Conventions">1.3
+ Documentation Conventions</a></p>
+
+ <p class="TOCHeading"><a href="#Overview">2. Overview</a></p>
+
+ <p class="TOC"><a href="#Key_Elements">2.1 Key Elements</a></p>
+
+ <p class="TOC"><a href="#Implementation_Notes">2.2
+ Implementation Notes</a></p>
+
+ <p class="TOC"><a href="#Pipeline_Life-cycle">2.3 Pipeline
+ Life-cycle</a></p>
+
+ <blockquote>
+ <p class="TOC"><a href="#Initialization">2.3.1
+ Initialization</a></p>
+
+ <p class="TOC"><a href="#Method_Compilation">2.3.2 Method
+ Compilation</a></p>
+
+ <p class="TOC"><a href="#De-initialization">2.3.3
+ De-initialization</a></p>
+ </blockquote>
+
+ <p class="TOCHeading"><a href="#Command-line_Interface">3.
+ Command-line Interface</a></p>
+
+ <p class="TOCHeading"><a href="#PMF_Commands">4. PMF
+ Commands</a></p>
+
+ <p class="TOC"><a href="#Path_Definition">4.1 Path
+ Definition</a></p>
+
+ <p class="TOC"><a href="#Filter_Definition">4.2 Filter
+ Definition</a></p>
+
+ <p class="TOC"><a href="#Argument_Definition">4.3 Argument
+ Definition</a></p>
+
+ <p class="TOCHeading"><a href="#Logging_System">5. Logging
+ System</a></p>
+
+ <p class="TOC"><a href="#Defining_Streams">5.1 Defining
+ Streams</a></p>
+
+ <p class="TOC"><a href="#Assigning_a_Stream_to_a_File">5.2
+ Assigning a Stream to a File</a></p>
+
+ <blockquote>
+ <p class="TOC"><a href="#Using_Filename_Masks">5.2.1 Using
+ Filename Masks</a></p>
+
+ <p class="TOC"><a href="#Filename_Review">5.2.2 Filename
+ Review</a></p>
+ </blockquote>
+
+ <p class="TOC"><a href="#Using_Streams">5.3 Using
+ Streams</a></p>
+
+ <p class="TOCHeading"><a href="#Appendix">6. Appendix</a></p>
+
+ <p class="TOC">
+ <a href="#General_Command-line_Syntax_Specification">6.1
+ General Command-line Syntax Specification</a></p>
+
+ <h1><a name="Revision_History"
+ id="Revision_History"></a>Revision History</h1>
+
+ <table border="0"
+ cellpadding="0"
+ width="100%">
+ <tr>
+ <th class="TableHeading">Version</th>
+
+ <th class="TableHeading">Version Information</th>
+
+ <th class="TableHeading">Date</th>
+ </tr>
+
+ <tr>
+ <td class="TableCell">Initial version</td>
+
+ <td class="TableCell">Sergey Ivashin, Svetlana
+ Konovalova: document created.</td>
+
+ <td class="TableCell">October 30 , 2006</td>
+ </tr>
+ </table>
+
+ <h1><a name="About_This_Document"
+ id="About_This_Document"></a>1. About This Document</h1>
+
+ <h2><a name="Purpose"
+ id="Purpose"></a>1.1 Purpose</h2>
+
+ <p>The document is a comprehensive description of the
+ <i>pipeline management framework</i> that provides complete
+ control over just-in-time compilation process through the
+ Java<a href="#*">*</a> property mechanism. The description
+ covers the PMF application to the command-line interface and to
+ the Jitrino logging system.</p>
+
+ <p>PMF is introduced in the Jitrino component description,
+ whereas the current document gives details on its internal
+ design and specifics. The current document adds examples and
+ usage instructions to the general definition of PMF given in
+ the component description.</p>
+
+ <h2><a id="Intended_Audience"
+ name="Intended_Audience"></a>1.2 Intended Audience</h2>
+
+ <p>The target audience for the document includes a wide
+ community of DRLVM developers interested in understanding
+ Jitrino internals and in improving them. The document assumes
+ that readers understand the concepts of
+ <a href="#PMF_Commands">PMF</a> and just-in-time
+ compilation.</p>
+
+ <h2><a id="Documentation_Conventions"
+ name="Documentation_Conventions"></a>1.3 Documentation
+ Conventions</h2>
+
+ <p>This document uses the <a href="conventions.htm">unified
+ conventions</a> for the DRL documentation kit.</p>
+
+ <p class="backtotop"><a href="#top">Back to Top</a></p>
+
+ <h1><a id="Overview"
+ name="Overview"></a>2. Overview</h1>
+
+ <p>The document contains the detailed description of the
+ Jitrino pipeline management framework (PMF). For a high-level
+ PMF overview, refer to the <a href="#Jitrino.html">Jitrino
+ document</a>.</p>
+
+ <h2><a id="Key_Elements"
+ name="Key_Elements"></a>2.1 Key Elements</h2>
+
+ <p>This section contains a detailed description of the PMF key
+ elements.</p>
+
+ <dl>
+ <dt><a id="Pipeline"
+ name="Pipeline"></a>Pipeline</dt>
+
+ <dd>
+ <p>The <i>pipeline</i> is a sequence of steps
+ representing the compilation process for a set of
+ methods. You can create several pipelines for a single
+ JIT, targeting each to compile a particular set of
+ methods. Each instance of the JIT compiler has one
+ <i>common pipeline</i>, which has an empty method
+ filter. Thus, the common pipeline is applied if a
+ compiled method matched no method filter of other
+ pipelines. For more information on the common pipeline,
+ refer to the
+ <a href="#Initialization">Initialization</a> section of
+ the current document.</p>
+ </dd>
+
+ <dt><a id="Method_Filter"
+ name="Method_Filter"></a>Method Filter</dt>
+
+ <dd>
+ <p>The <i>method filter</i> is used to choose a
+ particular pipeline for a method being compiled. Filter
+ elements make up a filter expression, as follows:<br />
+ <code><<b>class_name</b>><<b>method_name</b>><<b>
+ method_signature</b>></code>.<br />
+ Any or all of these elements can be blank. If all
+ elements of a filter expression are empty strings, the
+ filter is empty. Empty filters are used in the
+ compilation of a common pipeline.</p>
+ </dd>
+
+ <dt><a id="Pipeline_Step"
+ name="Pipeline_Step"></a>Pipeline Step</dt>
+
+ <dd>
+ <p>The <i>pipeline step</i> is a pipeline element that
+ stores a reference to an action object and its full
+ name. In the pipeline definition a step is represented
+ by its textual name.</p>
+ </dd>
+
+ <dt><a id="Action"
+ name="Action"></a>Action</dt>
+
+ <dd>
+ <p>The <i>action</i> is an object representing a
+ certain independent transformation of compiled code.
+ Each action must be declared as a subclass of the
+ <code>Jitrino::Action</code> class. Therefore, all
+ actions have a common set of properties and methods,
+ namely:</p>
+
+ <ul>
+ <li>The <code>name</code> property used to assign a
+ unique name to each JIT action</li>
+
+ <li>The <code>init()</code> and
+ <code>deinit()</code> methods used to
+ <a href="#Initialization">initialize</a> and
+ <a href="#De-initialization">de-initialize</a> the
+ JIT</li>
+
+ <li>The <code>createSession()</code> method used to
+ create
+ <a href="#SessionAction"><code>SessionAction</code></a></li>
+ </ul>
+
+ <p class="note">Note</p>
+
+ <p class="notetext">Actions do not have the
+ <code>run()</code> method and cannot be called directly
+ in the pipeline. The <code>SessionAction</code> object
+ is used instead.</p>
+
+ <p>The system creates <code>Action</code> objects once
+ per JIT execution and uses them to store data between
+ compilation sessions.</p>
+
+ <p class="class"><a id="SessionAction"
+ a=""
+ name="SessionAction"><code>SessionAction</code></a></p>
+
+ <p>A <code>SessionAction</code> object created by PMF
+ to transform code in a particular compilation session.
+ <code>SessionAction</code> must be declared as a
+ subclass of the <code>Jitrino::SessionAction</code>
+ class, which has the following methods:</p>
+
+ <ul>
+ <li>The <code>getAction()</code> method to get the
+ reference to the parent <code>Action</code>
+ object</li>
+
+ <li>The <code>run()</code> method to do the work
+ for the action object</li>
+ </ul>
+
+ <p>Instances of <code>SessionAction</code> are created
+ at the start of method compilation and destroyed at the
+ end of compilation. In other words, they are created
+ and destroyed every time when a pipeline with the
+ corresponding action is selected for method
+ compilation. Therefore, no data can be saved in this
+ object between compilation sessions.</p>
+ </dd>
+
+ <dt><a id="IAction"
+ name="IAction"></a>IAction</dt>
+
+ <dd>
+ <p>The <code>IAction</code> class is a common ancestor
+ of the <code>Action</code> and
+ <code>SessionAction</code> classes, which contains
+ service methods that may be accessed from both child
+ classes; for example, argument processing methods or
+ methods for obtaining a reference to the corresponding
+ pipeline.</p>
+ </dd>
+ </dl>
+
+ <p style="text-align: center"><img src="images/Pipeline.PNG"
+ alt="package" /></p>
+
+ <p class="special">Figure 1: The Role of Pipelines in the JIT
+ Compilation Process</p>
+
+ <p>Figure 1 demonstrates the role of pipelines in the JIT
+ compilation process.</p>
+ <p class="backtotop"><a href="#top">Back to Top</a></p>
+
+ <h2><a id="Implementation_Notes"
+ name="Implementation_Notes"></a>2.2 Implementation
+ Notes</h2>
+
+ <p>When using the PMF implementation, please note the
+ following:</p>
+
+ <ul>
+ <li>The common pipeline is mandatory, others are
+ optional.</li>
+
+ <li>An optional pipeline must be assigned to a unique and
+ non-empty filter expression.</li>
+
+ <li>Different pipeline steps can refer to the same
+ action.</li>
+
+ <li>Different pipelines can have different sets of steps
+ and different orders of steps.</li>
+
+ <li>Each pipeline step can be supplied with a unique
+ parameter.</li>
+ </ul>
+
+ <p class="backtotop"><a href="#top">Back to Top</a></p>
+
+ <h2><a id="Pipeline_Life-Cycle"
+ name="Pipeline_Life-cycle"></a>2.3 Pipeline Life-cycle</h2>
+
+ <h3><a id="Initialization"
+ name="Initialization"></a>2.3.1 Initialization</h3>
+
+ <p>The common pipeline is created at the JIT initialization.
+ All other pipelines are created just before their first use.
+ Therefore, an optional pipeline is only initialized when a
+ compiled method matches its filter.</p>
+
+ <p>During pipeline creation, the compiler iterates over all its
+ steps. For each step, the compiler creates an instance of the
+ referenced <code>Action</code> object and calls the
+ <code>Action::init() method</code>. At this point, all action
+ parameters are available and the <code>Action::init()</code>
+ method can use any of the <code>IAction::getArg</code> methods
+ to retrieve action parameters. For efficiency purposes,
+ parameters should be processed at the initialization phase, not
+ during compilation of each method.</p>
+
+ <p class="note">Note</p>
+
+ <p class="notetext">You can call the
+ <code>IAction::getArg</code> method from
+ <code>SessionAction::run()</code> during compilation of a
+ method, but it is a less effective way of parameter processing.
+ The SessionAction object has access to its parent
+ <code>Action</code> object and therefore, can access data
+ prepared during the initialization phase.</p>
+
+ <h3><a id="Method_Compilation"
+ name="Method_Compilation"></a>2.3.2 Method Compilation</h3>
+
+ <p>At this stage, the compiler selects the pipeline for the
+ given method using the filter expression in the method filter
+ and proceeds to compile a method. If the method matches several
+ filters, then the pipeline with the longest filter expression
+ is selected, that is PMF always chooses the filter with more
+ characters in its expression. PMF prohibits creation of
+ different pipelines with the same filter expression.</p>
+
+ <p>To compile the method, JIT executes the selected pipeline:
+ iterates over all its steps, creates a
+ <code>SessionAction</code> object for each step, calls the
+ <code>run()</code> method in each object, and destroys it.</p>
+
+ <h3><a id="De-initialization"
+ name="De-initialization"></a>2.3.3 De-initialization</h3>
+
+ <p>At the JIT de-initialization phase all created pipelines are
+ destroyed. The <code>Action::deinit()</code> method is called
+ for every step in a pipeline during its de-initialization.</p>
+
+ <p class="backtotop"><a href="#top">Back to Top</a></p>
+
+ <h1><a id="Command-line_Interface"
+ name="Command-line_Interface"></a>3. Command-line
+ Interface</h1>
+
+ <p>The <i>command-line interface</i> is based on system
+ properties defined by "property = value" relations. At the
+ initialization phase, all properties are stored in the table of
+ VM properties. Depending on the configuration mode, VM can
+ create several JITs. In this case, each JIT reads this table
+ and selects properties independently; therefore, different JITs
+ have different property sets.</p>
+
+ <p>The general form of the JIT command is the following:</p>
+ <pre>
+-Djit.<<b>JIT</b>>.<<b>pipeline</b>>.<<b>parameter</b>>=<<b>value</b>>
+</pre>
+
+ <p>Where</p>
+
+ <ul>
+ <li>
+ <code>-Djit.</code> is the mandatory prefix enabling
+ JIT commands selection from VM commands.
+
+ <p class="note">Note</p>
+
+ <p class="notetext">The Jitrino command-line interface
+ ignores all commands that do not start with this
+ prefix.</p>
+ </li>
+
+ <li>
+ <code><<b>JIT</b>></code> specifies the JIT name.
+
+
+ <p class="note">Note</p>
+
+ <p class="notetext">JITs are created by
+ <a href="#EM.html">Execution Manager</a> (EM) using
+ information from the command line and/or
+ <a href="http://incubator.apache.org/harmony/subcomponents/drlvm/emguide.html">
+ <code>execution manager configuration</code>
+ file</a>.</p>
+ </li>
+
+ <li><code><<b>pipeline</b>></code> specifies the
+ pipeline name.</li>
+
+ <li><code><<b>parameter</b>></code> and
+ <code><<b>value</b>></code> are used to construct one
+ of the three available basic commands:
+ <a href="#Filter_Definition">filter definition</a>,
+ <a href="#Path_Definition">path definition</a> and
+ <a href="#Argument_Definition">argument
+ definition</a>.</li>
+ </ul>
+
+ <p>Both <code><<b>JIT</b>></code> and
+ <code><<b>pipeline</b>></code> elements define the
+ command scope in the following way:</p>
+
+ <ul>
+ <li>If the <code><<b>JIT</b>></code> element is
+ omitted, the scope of the command consists of all existing
+ JITs.</li>
+
+ <li>If the <code><<b>pipeline</b>></code> element is
+ omitted, the scope of the command consists of all pipelines
+ existing in the specified JIT.</li>
+
+ <li>If both <code><<b>JIT</b>></code> and
+ <code><<b>pipeline</b>></code> are omitted, the scope
+ of the command consists of all pipelines of all JITs.<br />
+ <br /></li>
+ </ul>
+
+ <p>Commands can be specified on the command line or in the EM
+ configuration file. Most important commands are usually placed
+ in the
+ <a href="http://incubator.apache.org/harmony/subcomponents/drlvm/emguide.html">
+ <code>EM configuration</code> file</a>, so Jitrino can be used
+ without any commands on the command line.</p>
+
+ <p>The order of commands on the command line and in the
+ external file is not significant.</p>
+
+ <p>Another way to deal with a set of commands is to store it in
+ a <i>command file</i> and read this file with a special <i>read
+ command</i>:</p>
+ <pre>
+-Djit.read=<<b>command filename</b>>
+</pre>
+
+ <p class="note">Note</p>
+
+ <p class="notetext">Write commands in the command file without
+ the prefix <code>-Djit</code>. The <code>read</code> command
+ itself can be used in the command file. The command file can
+ contain empty lines and comment lines starting with
+ <code>#</code> or <code>//</code>.</p>
+
+ <p>For information on the general command line syntax
+ specification, refer to the
+ <a href="#Appendix">Appendix</a>.</p>
+
+ <p class="backtotop"><a href="#top">Back to Top</a></p>
+
+ <h1><a id="PMF_Commands"
+ name="PMF_Commands"></a>4. PMF Commands</h1>
+
+ <p>To control the JIT compilation process, PMF uses
+ <a href="#Path_Definition">path definition</a>,
+ <a href="#Filter_Definition">filter definition</a> and
+ <a href="#Argument_definition">argument definition</a>
+ commands.</p>
+
+ <h2><a id="Path_Definition"
+ name="Path_Definition"></a>4.1 Path Definition</h2>
+
+ <p>A pipeline can be described as an ordered set of terminal
+ leafs of a path tree. The tree is a purely abstract concept
+ introduced to describe the pipeline construction process. Each
+ non-terminal node of the tree is called a <i>path</i> and
+ defined by the following <i>path definition</i> command:</p>
+ <pre>
+-Djit.<<b>JIT</b>>.<<b>pipeline</b>>.path.<<b>name</b>>=<<b>child1</b>>,<<b>child2</b>>,...
+</pre>
+
+ <p>The given command introduces a node with the specified name
+ and enumerates all its direct descendants - children. If a
+ child is a terminal node, it is treated as the name of the
+ action; if not, then the child must be another path.</p>
+
+ <p>For each pipeline, define one path with the
+ <<b>name</b>> element omitted, which is called the
+ <i>root path</i>. Each path must have a unique definition.</p>
+
+ <p>Each action in the pipeline has a unique <i>full name</i>
+ consisting of all node names from the root to the action
+ itself. The root node is excluded because it has no name. More
+ than one instance of the same action can exist, as long as each
+ instance has a unique full name.</p>
+
+ <p class="example">Example</p>
+
+ <p class="exampletext"><code><b>OPT</b></code> is the JIT name
+ and <code><b>a</b></code>, <code><b>b</b></code> and
+ <code><b>c</b></code> are the action names.</p>
+ <pre>
+-Djit.OPT.path=M,N
+-Djit.OPT.path.M=a
+-Djit.OPT.path.N=b,c
+</pre>
+
+ <p class="exampletext">The given commands describe the simple
+ path tree:</p>
+
+ <p style="text-align: center"><img src="images/Pipeline1.png"
+ alt="package" /></p>
+
+ <p class="special">Figure 2: A Path Tree of a Common
+ Pipeline</p>
+
+ <p class="exampletext">The following resulting pipeline is
+ constructed from the aforementioned tree:<br />
+ <code><b>a</b></code>, <code><b>b</b></code>,
+ <code><b>c</b></code></p>
+
+ <p class="exampletext">The pipeline above is common, because it
+ has no method filter. Each action of the given pipeline has a
+ unique full name.</p>
+
+ <table width="31%"
+ height="161"
+ cellpadding="0">
+ <tr>
+ <th class="TableHeading">Action</th>
+
+ <th class="TableHeading">Full Name</th>
+ </tr>
+
+ <tr>
+ <td class="TableCell">a</td>
+
+ <td class="TableCell">M.a</td>
+ </tr>
+
+ <tr>
+ <td width="30%"
+ class="TableCell">b</td>
+
+ <td width="30%"
+ class="TableCell">N.b</td>
+ </tr>
+
+ <tr>
+ <td width="30%"
+ class="TableCell">c</td>
+
+ <td width="30%"
+ class="TableCell">N.c</td>
+ </tr>
+ </table>
+
+ <p class="backtotop"><a href="#top">Back to Top</a></p>
+
+ <h2><a id="Filter_Definition"
+ name="Filter_Definition"></a>4.2 Filter Definition</h2>
+
+ <p>To define a filter, use the following command format:</p>
+ <pre>
+-Djit.<<b>JIT</b>>.<<b>pipeline</b>>.filter=<<b>class</b>>.<<b>method</b>><<b>signature</b>>
+</pre>
+
+ <p>Where</p>
+
+ <ul>
+ <li><<code><b>pipeline</b></code>> is the required
+ element, which cannot be omitted.</li>
+
+ <li><<code><b>class</b></code>> is the name of the
+ class constituting the filter expression.</li>
+
+ <li><<code><b>method</b></code>> is the name of the
+ method constituting the filter expression.</li>
+
+ <li><<code><b>signature</b></code>> is the signature
+ of the method constituting the filter expression.</li>
+ </ul>
+
+ <p class="note">Note</p>
+
+ <p class="notetext">In the filter definition, the
+ <code>method</code> and the <code>signature</code> elements
+ have no period <code>.</code> between them.</p>
+
+ <p>You must follow the VM notation for the described elements.
+ You are free to omit some elements, but at least one must be
+ present.</p>
+
+ <p>If each of three elements of the method name starts with the
+ corresponding element of the filter expression, the compiled
+ method matches the filter.</p>
+
+ <p class="example">Example</p>
+ <pre>
+-Djit.OPT.p.filter=java/lang/Thread.check
+</pre>
+
+ <p class="exampletext">The following methods can match the
+ given filter:<br />
+ <code>java/lang/ThreadGroup.checkAccess()V</code><br />
+ <code>java/lang/Thread.checkGCWatermark()V</code><br />
+ <code>java/lang/Thread.checkAccess()V</code></p>
+
+ <p>To continue the example, methods can equally match a less
+ detailed filter expression, such as
+ <code>java/lang.check</code>. However, PMF would use the more
+ specific filter, as described in the
+ <a href="#Method_Compilation">Method Compilation</a>
+ section.</p>
+
+ <p class="example">Example</p>
+ <pre>
+-Djit.OPT.path=M,N
+-Djit.OPT.path.M=a
+-Djit.OPT.path.N=b,c
+-Djit.OPT.p.path=M,N,O
+-Djit.OPT.p.path.O=a
+-Djit.OPT.p.filter=java/lang/Thread.check
+</pre>
+
+ <p class="exampletext">The commands above are associated with
+ the following path trees:</p>
+
+ <p style="text-align: center"><img src="images/Pipelines2.png"
+ alt="package" /></p>
+
+ <p class="special">Figure 3: An Example of Path Trees for
+ Multiple Pipelines</p>
+
+ <p class="exampletext">The following resulting pipelines are
+ constructed from the aforementioned trees:<br />
+ (<code>common</code>) <code><b>a</b></code>,
+ <code><b>b</b></code>, <code><b>c</b></code><br />
+ (<code>p</code>)
+ <code><b>a</b></code>, <code><b>b</b></code>,
+ <code><b>c</b></code>, <code><b>a</b></code></p>
+
+ <p class="note">Note</p>
+
+ <p class="notetext">Path definitions <code><b>M</b></code> and
+ <code><b>N</b></code> in the pipeline <code><b>p</b></code> are
+ inherited from the common pipeline, because they were defined
+ in commands with the pipeline element omitted, but the root
+ path definition in the <code><b>p</b></code> pipeline was
+ overridden.</p>
+
+ <p class="backtotop"><a href="#top">Back to Top</a></p>
+
+ <h2><a id="Argument_Definition"
+ name="Argument_Definition"></a>4.3 Argument Definition</h2>
+
+ <p>To control the actions behavior, PMF supports an action
+ parameters passing convention. The parameter definition command
+ pattern is the following:</p>
+ <pre>
+-Djit.<<b>JIT</b>>.<<b>pipeline</b>>.arg.<<b>full name</b>>.<<b>param</b>>=<<b>value</b>>
+</pre>
+
+ <p>Where</p>
+
+ <ul>
+ <li><<b>param</b>> and <<b>value</b>> are
+ mandatory elements.</li>
+
+ <li><<b>JIT</b>>, <<b>pipeline</b>> and
+ <<b>full name</b>> are optional elements defining the
+ scope of the both.</li>
+ </ul>
+
+ <p>The <<b>full name</b>> element defines the parameter
+ scope in the following way:</p>
+
+ <ul>
+ <li>If <<b>full name</b>> addresses a certain action,
+ that is a terminal node, the parameter affects all
+ instances of this action.</li>
+
+ <li>If <<b>full name</b>> addresses not an action,
+ but a node with children, the parameter affects this node
+ and all its descendants.</li>
+
+ <li>If <<b>full name</b>> is omitted, the parameter
+ affects all actions in the pipeline.</li>
+ </ul>
+
+ <p class="example">Example</p>
+ <pre>
+-Djit.OPT.p.arg.a.verify=1
+</pre>
+
+ <p class="exampletext">The given command sets the
+ <<b>verify</b>> parameter for both <code><b>a</b></code>
+ instances, <code><b>M.a</b></code> and <code><b>O.a</b></code>,
+ to <b>1</b>. See Figure 3.</p>
+
+ <p>The table below gives several examples of essential commands
+ for the path trees based on Figure 3.</p>
+
+ <table>
+ <tr>
+ <th width="232"
+ class="TableHeading">Command</th>
+
+ <th width="98"
+ class="TableHeading">Omitted Element</th>
+
+ <th width="631"
+ class="TableHeading">Definition</th>
+ </tr>
+
+ <tr>
+ <td class="TableCell">
+ <code>-Djit.OPT.p.arg.N.b.verify=2</code></td>
+
+ <td class="TableCell">
+ <center>
+ —
+ </center>
+ </td>
+
+ <td class="TableCell">The parameter <code>verify</code>
+ with value 2 is available only to action
+ <code><b>b</b></code> with the full name
+ <code><b>N.b</b></code> in pipeline
+ <code><b>p</b></code> of JIT
+ <code><b>OPT</b></code>.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell">
+ <code>-Djit.OPT.p.arg.N.verify=2</code></td>
+
+ <td class="TableCell">
+ <center>
+ —
+ </center>
+ </td>
+
+ <td class="TableCell">The parameter <code>verify</code>
+ is available for actions <code><b>b</b></code> and
+ <code><b>c</b></code> simultaneously.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell">
+ <code>-Djit.OPT.p.arg.verify=2</code></td>
+
+ <td class="TableCell"><code><<b>full
+ name</b>></code></td>
+
+ <td class="TableCell">The parameter <code>verify</code>
+ is available for all actions <code><b>a</b></code>,
+ <code><b>b</b></code>, <code><b>c</b></code> and
+ <code><b>a</b></code> in pipeline
+ <code><b>p</b></code>.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell">
+ <code>-Djit.OPT.arg.N.verify=2</code></td>
+
+ <td class="TableCell">
+ <code><<b>pipeline</b>></code></td>
+
+ <td class="TableCell">The parameter <code>verify</code>
+ is available for <code><b>b</b></code> and
+ <code><b>c</b></code> actions for common and
+ <code><b>p</b></code> pipelines of JIT
+ <code><b>OPT</b></code> .</td>
+ </tr>
+ </table>
+
+ <p>The special form of argument definition commands controls
+ the pipeline construction process:</p>
+ <pre>
+-Djit.<<b>JIT</b>>.<<b>pipeline</b>>.arg.<<b>full name</b>>=on
+-Djit.<<b>JIT</b>>.<<b>pipeline</b>>.arg.<<b>full name</b>>=off
+</pre>
+
+ <p class="note">Note</p>
+
+ <p class="notetext">In the given form of the argument
+ definition, the <<b>param</b>> element is absent and only
+ two values for <<b>value</b>> exist: <code>on</code> and
+ <code>off</code>.</p>
+
+ <p>The <code>off</code> value disables the addressed node and
+ all its descendants, while the <code>on</code> value enables
+ the node and its descendants. When constructed, a pipeline does
+ not include any disabled actions.</p>
+
+ <p class="example">Example</p>
+
+ <p class="exampletext">To exclude action <code><b>b</b></code>
+ from the pipeline, apply the following command:</p>
+ <pre>
+-Djit.OPT.p.arg.N.b=off
+</pre>
+
+ <p>To enable/disable nodes directly in the path definition
+ command, add state characters immediately after the node name,
+ videlicet:</p>
+
+ <table width="53%"
+ height="161"
+ cellpadding="0">
+ <tr>
+ <th class="TableHeading">Character</th>
+
+ <th class="TableHeading">Corresponding Node
+ Meaning</th>
+ </tr>
+
+ <tr>
+ <td class="TableCell">
+ <center>
+ +
+ </center>
+ </td>
+
+ <td class="TableCell">enabled</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell">
+ <center>
+ —
+ </center>
+ </td>
+
+ <td class="TableCell">disabled</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell">
+ <center>
+ !
+ </center>
+ </td>
+
+ <td class="TableCell">cannot be disabled</td>
+ </tr>
+ </table>
+
+ <p>The following command states that <code>c1</code> is
+ enabled, <code>c2</code> is disabled and <code>c3</code> is
+ enabled and mandatory:</p>
+ <pre>
+-Djit.<<b>JIT</b>>.<<b>pipeline</b>>.path.<<b>name</b>>=c1+,c2-,c3!
+</pre>
+
+ <p>If you try to disable any mandatory node with the
+ <code>off</code> command, the fatal error occurs.</p>
+
+ <p class="backtotop"><a href="#top">Back to Top</a></p>
+
+ <h1><a id="Logging_System"
+ name="Logging_System"></a>5. Logging System</h1>
+
+ <p>The <i>logging system</i> supports diagnostic messages from
+ pipeline actions. The VM property mechanism fully controls the
+ system.</p>
+
+ <h2><a id="Stream_Definition"
+ name="Defining_Streams"></a>5.1 Defining Streams</h2>
+
+ <p>A set of <i>log streams</i> is used for logging in Jitrino.
+ Each log stream has a name. The name of the log stream is not
+ related to the name of the file, to which the stream is
+ assigned. The class <code>Jitrino::LogStream</code> is the
+ program representation of a log stream. This class is similar
+ to the <code>std::ostream</code> class in the defining operator
+ <code><<</code> and other useful methods, such as
+ <code>printf()</code> and <code>flush()</code>. To obtain the
+ reference to the underlying <code>std::ostream</code> instance,
+ call the <code>out()</code> method.</p>
+
+ <p>Streams can be accessed by name or by ID. The stream ID can
+ be obtained from its name by using the
+ <code>IAction::getLogStreamID()</code> method. For performance
+ reasons, several most frequently used streams, so-called
+ <i>known</i> streams, have predefined IDs:</p>
+
+ <table>
+ <tr>
+ <th class="TableHeading">Stream Name</th>
+
+ <th class="TableHeading">Stream ID</th>
+
+ <th class="TableHeading">Output</th>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>info</code></td>
+
+ <td class="TableCell"><code>LogStream::INFO</code></td>
+
+ <td class="TableCell">The protocol of compilation: JIT
+ and pipeline names, the method name and number, and so
+ on.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>rt</code></td>
+
+ <td class="TableCell"><code>LogStream::RT</code></td>
+
+ <td class="TableCell">Run-time output not related to
+ compiled methods.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>ct</code></td>
+
+ <td class="TableCell"><code>LogStream::CT</code></td>
+
+ <td class="TableCell">Compile-time diagnostic.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>irdump</code></td>
+
+ <td class="TableCell">
+ <code>LogStream::IRDUMP</code></td>
+
+ <td class="TableCell">The dump of internal Jitrino
+ structures for a compiled method.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>dotdump</code></td>
+
+ <td class="TableCell">
+ <code>LogStream::DOTDUMP</code></td>
+
+ <td class="TableCell">The dump of internal Jitrino
+ structures in the <code>.dot</code> format.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>dbg</code></td>
+
+ <td class="TableCell"><code>LogStream::DBG</code></td>
+
+ <td class="TableCell">Debug information.</td>
+ </tr>
+ </table>
+
+ <p>To enable outputting log information to a stream, enter a
+ command of the following syntax:</p>
+ <pre>
+-Djit.<<b>JIT</b>>.<<b>pipeline</b>>.arg.<<b>full name</b>>.log=<<b>stream1</b>>,<<b>stream2</b>>,...
+</pre>
+
+ <p>The left part of the command specifies the name of the JIT
+ compiler and the compilation pipeline to be used, whereas the
+ right part contains the names of the streams that you want to
+ enable. Use the same syntax to enable a custom stream: write an
+ arbitrary name for it and enable the stream with this
+ command.</p>
+
+ <p class="note">Note</p>
+
+ <p class="notetext">If program output is directed to a disabled
+ stream, the output is lost and no error diagnostic is
+ produced.</p>
+
+ <p>The enabling command follows the general scope of rules: the
+ stream is enabled for the node specified in the command and all
+ its descendants.</p>
+
+ <p>Streams defined for different nodes are different streams,
+ though they can have the same name.</p>
+
+ <p class="example">Example</p>
+
+ <p class="exampletext">The following commands enable two
+ different streams, though both can be accessed from actions
+ <code><b>N.b</b></code> and <code><b>N.c</b></code> by the same
+ name. The streams can be assigned to different files.</p>
+ <pre>
+-Djit.OPT.p.arg.N.b.log=ct
+-Djit.OPT.p.arg.N.c.log=ct
+</pre>
+
+ <p class="backtotop"><a href="#top">Back to Top</a></p>
+
+ <h2><a id="Assigning_a_Stream_to_a_File"
+ name="Assigning_a_Stream_to_a _File"></a>5.2 Assigning a
+ Stream to a File</h2>
+
+ <p>To assign a stream to a file, use the following command
+ syntax:</p>
+ <pre>
+-Djit.<<b>JIT</b>>.<<b>pipeline</b>>.arg.<<b>full name</b>>.log.<<b>stream</b>>.file=<<b>filename mask</b>>
+</pre>
+
+ <p>In the given command, the <<b>filename mask</b>>
+ element constructs a filename for the stream. All characters
+ from this mask are copied to the resulting filename literally
+ except macros, which are expanded and the result of expansion
+ is copied to the filename. Below is the list of available
+ macros.</p>
+
+ <table>
+ <tr>
+ <th class="TableHeading">Macro</th>
+
+ <th class="TableHeading">Expands To</th>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>%jit%</code></td>
+
+ <td class="TableCell">The name of the JIT that is
+ compiling the method.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>%class%</code></td>
+
+ <td class="TableCell">The method class name with
+ <code>/</code> changed to <code>_</code></td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>%class_tree%</code></td>
+
+ <td class="TableCell">The method class name with
+ <code>/</code> preserved.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>%method%</code></td>
+
+ <td class="TableCell">The method name and signature in
+ VM notation.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>%seqnb%</code></td>
+
+ <td class="TableCell">The global sequential number of
+ the current compilation.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>%log%</code></td>
+
+ <td class="TableCell">The name of the stream.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>%thread%</code></td>
+
+ <td class="TableCell">The number of the thread
+ compiling the method.</td>
+ </tr>
+ </table>
+
+ <p>In most cases, a program can access the stream file from
+ concurrent threads, so that all stream operations are
+ synchronized. However, if a filename mask for the stream
+ contains the <code>%thread%</code> macro, this file is
+ thread-specific and access to it is not synchronized.</p>
+
+ <h3><a id="Using_File-name_Masks"
+ name="Using_Filename_Masks"></a>5.2.1 Using Filename
+ Masks</h3>
+
+ <p>For all streams, the following default filename mask is
+ used:</p>
+ <pre>
+log/%jit%/%class%/%method%/%log%.log
+</pre>
+
+ <p>For example, for an enabled stream <code>abc</code> with no
+ assigned filename mask, the log file is in the same directory
+ with other known stream files, and its name is
+ <code>abc.log</code>.</p>
+
+ <p>All known streams have hard-coded default filename masks,
+ described in the table below. These masks are used if no
+ assignment is made with the corresponding command.</p>
+
+ <table width="451">
+ <tr>
+ <th width="110"
+ class="TableHeading">Stream Name</th>
+
+ <th width="298"
+ class="TableHeading">Default Filename Mask</th>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>info</code></td>
+
+ <td class="TableCell"><code>log/info.log</code></td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>rt</code></td>
+
+ <td class="TableCell"><code>log/rt.log</code></td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>ct</code></td>
+
+ <td class="TableCell">
+ <code>log/%jit%/%class%/%method%/ct.log</code></td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>irdump</code></td>
+
+ <td class="TableCell">
+ <code>log/%jit%/%class%/%method%/irdump.log</code></td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>dotdump</code></td>
+
+ <td class="TableCell">
+ <code>log/%jit%/%class%/%method%/.dot [special
+ case]</code></td>
+ </tr>
+ </table>
+
+ <p class="example">Exception</p>
+
+ <p class="exampletext">Jitrino writes dot-dumps to the
+ <code>dotdump</code> stream and produces two <code>.dot</code>
+ files for each action: <i>before</i> and <i>after</i> execution
+ of an action. To handle these correctly, the enabled dot-dumper
+ opens the <code>dotdump</code> stream before executing the
+ action, writes to the stream and closes it. After executing the
+ action, the dot-dumper performs the same operation. Each time,
+ the dot-dumper adds a suffix that indicates the sequence of
+ actions to the tail of the stream filename <code>.dot</code>,
+ as follows:</p>
+ <pre>
+ .<<b>action_nb</b>>.<<b>action_name</b>>.before.dot
+ .<<b>action_nb</b>>.<<b>action_name</b>>.after.dot
+</pre>
+
+ <p>In the command above, the <<b>action name</b>> element
+ is the name of the action and <<b>action_nb</b>> is the
+ sequential number of the action in the current pipeline.</p>
+
+ <h3><a id="File_Name_Review"
+ name="Filename_Review"></a>5.2.2 Filename Review</h3>
+
+ <p>Names of all open stream files are reviewed at the beginning
+ of method compilation, because the stream file name can depend
+ on the name of the compiled method. If the name is changed as
+ the result of the dependency on the compiled method name, the
+ file is closed and another file with the new calculated name is
+ opened. If the name is not changed, no action is performed. If
+ the same file name is assigned to different streams, a single
+ file is opened and all the assigned streams use it.</p>
+
+ <p>If a file used for logging gets closed as the result of
+ filename recalculation, its name is saved in a special list
+ that PMF maintains. For every file opened for logging output,
+ the PMF checks the list. If the name is found, the file is
+ opened in the <i>append</i> mode. This approach prevents from
+ overwriting logging files during a single Jitrino run.</p>
+
+ <p>You can use the following commands to control the
+ append/truncate mode for the log files that are opened for the
+ first time:</p>
+ <pre>
+-Djit.<<b>JIT</b>>.<<b>pipeline</b>>.arg.<<b>full name</b>>.log.<<b>stream</b>>.append=true
+-Djit.<<b>JIT</b>>.<<b>pipeline</b>>.arg.<<b>full name</b>>.log.<<b>stream</b>>.append=false
+</pre>
+
+ <p class="backtotop"><a href="#top">Back to Top</a></p>
+
+ <h2><a id="Using_Stream"
+ name="Using_Streams"></a>5.3 Using Streams</h2>
+
+ <p>A typical usage pattern for Jitrino action is the
+ following:</p>
+
+ <ol>
+ <li>Find the required stream using its name or ID.</li>
+
+ <li>(optional) Test whether the stream is enabled.</li>
+
+ <li>Output to the stream using the insertion operator
+ <code><<</code> or <code>printf()</code> method.</li>
+ </ol>
+
+ <p class="example">Example</p>
+ <pre>
+ LogStream& irdump = log(LogStream::IRDUMP);
+
+ if (irdump.isEnabled()) {
+ irdump << "Opt: Running " << getName() << stl::endl;
+ }
+</pre>
+
+ <p class="backtotop"><a href="#top">Back to Top</a></p>
+
+ <h1><a id="Appendix"
+ name="Appendix"></a>6. Appendix</h1>
+
+ <h2><a id="General_Command-line_Syntax_Specification"
+ name="General_Command-line_Syntax_Specification"></a>6.1
+ General Command-line Syntax Specification</h2>
+ <pre>
+<cmd> : <prefix> <filter def>
+ <prefix> <path def>
+ <prefix> <arg def>
+ <prefix> <file read>
+
+<prefix> : -Djit.
+
+<base> : [ <JIT> . ] [ <pipeline> . ]
+
+<JIT> : <name>
+
+<pipeline> : <name>
+
+
+<filter def> : <base> filter = <filter spec>
+
+<filter spec> : [ <class> ] [ . <method> [ <signature> ] ]
+ [ <class> ] [ :: <method> [ <signature> ] ]
+
+
+<path def> : <base> path . <node> = <path items>
+ <base> path = <path items>
+
+<path items> : <path item>
+ <path items> , <path item>
+
+<path item> : {<node> | <action >} [{ ! | + | - }]
+
+<node> : <name>
+
+<action> : <name>
+
+
+<arg def> : <base> arg [ <full name> . ] <arg name> = <arg value>
+ <base> arg <full name> = {off | on}
+
+<full name> : <path item>
+ <full name> . <path item>
+
+<arg name> : <name>
+
+<arg value> : <string>
+
+
+<file read> : read = <file name>
+
+</pre>
+
+ <p class="backtotop"><a href="#top">Back to Top</a></p>
+
+ <p><a id="*"
+ name="*">*</a> Other brands and names are the property of
+ their respective owners.</p>
+</body>
+</html>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+ <meta http-equiv="Content-Type"
+ content="text/html; charset=us-ascii" />
+ <link rel="Stylesheet"
+ type="text/css"
+ href="site.css" />
+
+ <title>Jitrino Pipeline Management Framework</title>
+</head>
+
+<body>
+ <h1><a id="top"
+ name="top"></a>Jitrino Pipeline Management Framework</h1>
+
+ <p class="TOCHeading"><a href="#Revision_History">Revision
+ History</a></p>
+
+ <p class="TOCHeading">
+ <a href="#Disclaimer_and_Legal">Disclaimer and Legal
+ Information</a></p>
+
+ <p class="TOCHeading"><a href="#About_This_Document">1. About
+ This Document</a></p>
+
+ <p class="TOC"><a href="#Purpose">1.1 Purpose</a></p>
+
+ <p class="TOC"><a href="#Intended_Audience">1.2 Intended
+ Audience</a></p>
+
+ <p class="TOC"><a href="#Documentation_Conventions">1.3
+ Documentation Conventions</a></p>
+
+ <p class="TOCHeading"><a href="#Overview">2. Overview</a></p>
+
+ <p class="TOC"><a href="#Key_Elements">2.1 Key Elements</a></p>
+
+ <p class="TOC"><a href="#Implementation_Notes">2.2
+ Implementation Notes</a></p>
+
+ <p class="TOC"><a href="#Pipeline_Life-cycle">2.3 Pipeline
+ Life-cycle</a></p>
+
+ <blockquote>
+ <p class="TOC"><a href="#Initialization">2.3.1
+ Initialization</a></p>
+
+ <p class="TOC"><a href="#Method_Compilation">2.3.2 Method
+ Compilation</a></p>
+
+ <p class="TOC"><a href="#De-initialization">2.3.3
+ De-initialization</a></p>
+ </blockquote>
+
+ <p class="TOCHeading"><a href="#Command-line_Interface">3.
+ Command-line Interface</a></p>
+
+ <p class="TOCHeading"><a href="#PMF_Commands">4. PMF
+ Commands</a></p>
+
+ <p class="TOC"><a href="#Path_Definition">4.1 Path
+ Definition</a></p>
+
+ <p class="TOC"><a href="#Filter_Definition">4.2 Filter
+ Definition</a></p>
+
+ <p class="TOC"><a href="#Argument_Definition">4.3 Argument
+ Definition</a></p>
+
+ <p class="TOCHeading"><a href="#Logging_System">5. Logging
+ System</a></p>
+
+ <p class="TOC"><a href="#Defining_Streams">5.1 Defining
+ Streams</a></p>
+
+ <p class="TOC"><a href="#Assigning_a_Stream_to_a_File">5.2
+ Assigning a Stream to a File</a></p>
+
+ <blockquote>
+ <p class="TOC"><a href="#Using_Filename_Masks">5.2.1 Using
+ Filename Masks</a></p>
+
+ <p class="TOC"><a href="#Filename_Review">5.2.2 Filename
+ Review</a></p>
+ </blockquote>
+
+ <p class="TOC"><a href="#Using_Streams">5.3 Using
+ Streams</a></p>
+
+ <p class="TOCHeading"><a href="#Appendix">6. Appendix</a></p>
+
+ <p class="TOC">
+ <a href="#General_Command-line_Syntax_Specification">6.1
+ General Command-line Syntax Specification</a></p>
+
+ <h1><a name="Revision_History"
+ id="Revision_History"></a>Revision History</h1>
+
+ <table border="0"
+ cellpadding="0"
+ width="100%">
+ <tr>
+ <th class="TableHeading">Version</th>
+
+ <th class="TableHeading">Version Information</th>
+
+ <th class="TableHeading">Date</th>
+ </tr>
+
+ <tr>
+ <td class="TableCell">Initial version</td>
+
+ <td class="TableCell">Sergey Ivashin, Svetlana
+ Konovalova: document created.</td>
+
+ <td class="TableCell">October 30 , 2006</td>
+ </tr>
+ </table>
+
+ <h1><a name="Disclaimer_and_Legal"
+ id="Disclaimer_and_Legal"></a>Disclaimer and Legal
+ Information</h1>
+
+ <p>Copyright 2006 The Apache Software Foundation or its
+ licensors, as applicable.</p>
+
+ <p>Licensed under the Apache License, Version 2.0 (the
+ License); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+ <a href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a>.</p>
+
+ <p>Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an AS
+ IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ express or implied. See the License for the specific language
+ governing permissions and limitations under the License.</p>
+
+ <p class="backtotop"><a href="#top">Back to Top</a></p>
+
+ <h1><a name="About_This_Document"
+ id="About_This_Document"></a>1. About This Document</h1>
+
+ <h2><a name="Purpose"
+ id="Purpose"></a>1.1 Purpose</h2>
+
+ <p>The document is a comprehensive description of the
+ <i>pipeline management framework</i> that provides complete
+ control over just-in-time compilation process through the
+ Java<a href="#*">*</a> property mechanism. The description
+ covers the PMF application to the command-line interface and to
+ the Jitrino logging system.</p>
+
+ <p>PMF is introduced in the Jitrino component description,
+ whereas the current document gives details on its internal
+ design and specifics. The current document adds examples and
+ usage instructions to the general definition of PMF given in
+ the component description.</p>
+
+ <h2><a id="Intended_Audience"
+ name="Intended_Audience"></a>1.2 Intended Audience</h2>
+
+ <p>The target audience for the document includes a wide
+ community of DRLVM developers interested in understanding
+ Jitrino internals and in improving them. The document assumes
+ that readers understand the concepts of
+ <a href="#PMF_Commands">PMF</a> and just-in-time
+ compilation.</p>
+
+ <h2><a id="Documentation_Conventions"
+ name="Documentation_Conventions"></a>1.3 Documentation
+ Conventions</h2>
+
+ <p>This document uses the <a href="conventions.htm">unified
+ conventions</a> for the DRL documentation kit.</p>
+
+ <p class="backtotop"><a href="#top">Back to Top</a></p>
+
+ <h1><a id="Overview"
+ name="Overview"></a>2. Overview</h1>
+
+ <p>The document contains the detailed description of the
+ Jitrino pipeline management framework (PMF). For a high-level
+ PMF overview, refer to the <a href="#Jitrino.html">Jitrino
+ document</a>.</p>
+
+ <h2><a id="Key_Elements"
+ name="Key_Elements"></a>2.1 Key Elements</h2>
+
+ <p>This section contains a detailed description of the PMF key
+ elements.</p>
+
+ <dl>
+ <dt><a id="Pipeline"
+ name="Pipeline"></a>Pipeline</dt>
+
+ <dd>
+ <p>The <i>pipeline</i> is a sequence of steps
+ representing the compilation process for a set of
+ methods. You can create several pipelines for a single
+ JIT, targeting each to compile a particular set of
+ methods. Each instance of the JIT compiler has one
+ <i>common pipeline</i>, which has an empty method
+ filter. Thus, the common pipeline is applied if a
+ compiled method matched no method filter of other
+ pipelines. For more information on the common pipeline,
+ refer to the
+ <a href="#Initialization">Initialization</a> section of
+ the current document.</p>
+ </dd>
+
+ <dt><a id="Method_Filter"
+ name="Method_Filter"></a>Method Filter</dt>
+
+ <dd>
+ <p>The <i>method filter</i> is used to choose a
+ particular pipeline for a method being compiled. Filter
+ elements make up a filter expression, as follows:<br />
+ <code><<b>class_name</b>><<b>method_name</b>><<b>
+ method_signature</b>></code>.<br />
+ Any or all of these elements can be blank. If all
+ elements of a filter expression are empty strings, the
+ filter is empty. Empty filters are used in the
+ compilation of a common pipeline.</p>
+ </dd>
+
+ <dt><a id="Pipeline_Step"
+ name="Pipeline_Step"></a>Pipeline Step</dt>
+
+ <dd>
+ <p>The <i>pipeline step</i> is a pipeline element that
+ stores a reference to an action object and its full
+ name. In the pipeline definition a step is represented
+ by its textual name.</p>
+ </dd>
+
+ <dt><a id="Action"
+ name="Action"></a>Action</dt>
+
+ <dd>
+ <p>The <i>action</i> is an object representing a
+ certain independent transformation of compiled code.
+ Each action must be declared as a subclass of the
+ <code>Jitrino::Action</code> class. Therefore, all
+ actions have a common set of properties and methods,
+ namely:</p>
+
+ <ul>
+ <li>The <code>name</code> property used to assign a
+ unique name to each JIT action</li>
+
+ <li>The <code>init()</code> and
+ <code>deinit()</code> methods used to
+ <a href="#Initialization">initialize</a> and
+ <a href="#De-initialization">de-initialize</a> the
+ JIT</li>
+
+ <li>The <code>createSession()</code> method used to
+ create
+ <a href="#SessionAction"><code>SessionAction</code></a></li>
+ </ul>
+
+ <p class="note">Note</p>
+
+ <p class="notetext">Actions do not have the
+ <code>run()</code> method and cannot be called directly
+ in the pipeline. The <code>SessionAction</code> object
+ is used instead.</p>
+
+ <p>The system creates <code>Action</code> objects once
+ per JIT execution and uses them to store data between
+ compilation sessions.</p>
+
+ <p class="class"><a id="SessionAction"
+ a=""
+ name="SessionAction"><code>SessionAction</code></a></p>
+
+ <p>A <code>SessionAction</code> object created by PMF
+ to transform code in a particular compilation session.
+ <code>SessionAction</code> must be declared as a
+ subclass of the <code>Jitrino::SessionAction</code>
+ class, which has the following methods:</p>
+
+ <ul>
+ <li>The <code>getAction()</code> method to get the
+ reference to the parent <code>Action</code>
+ object</li>
+
+ <li>The <code>run()</code> method to do the work
+ for the action object</li>
+ </ul>
+
+ <p>Instances of <code>SessionAction</code> are created
+ at the start of method compilation and destroyed at the
+ end of compilation. In other words, they are created
+ and destroyed every time when a pipeline with the
+ corresponding action is selected for method
+ compilation. Therefore, no data can be saved in this
+ object between compilation sessions.</p>
+ </dd>
+
+ <dt><a id="IAction"
+ name="IAction"></a>IAction</dt>
+
+ <dd>
+ <p>The <code>IAction</code> class is a common ancestor
+ of the <code>Action</code> and
+ <code>SessionAction</code> classes, which contains
+ service methods that may be accessed from both child
+ classes; for example, argument processing methods or
+ methods for obtaining a reference to the corresponding
+ pipeline.</p>
+ </dd>
+ </dl>
+
+ <p style="text-align: center"><img src="images/Pipeline.PNG"
+ alt="package" /></p>
+
+ <p class="special">Figure 1: The Role of Pipelines in the JIT
+ Compilation Process</p>
+
+ <p>Figure 1 demonstrates the role of pipelines in the JIT
+ compilation process.</p>
+ <p class="backtotop"><a href="#top">Back to Top</a></p>
+
+ <h2><a id="Implementation_Notes"
+ name="Implementation_Notes"></a>2.2 Implementation
+ Notes</h2>
+
+ <p>When using the PMF implementation, please note the
+ following:</p>
+
+ <ul>
+ <li>The common pipeline is mandatory, others are
+ optional.</li>
+
+ <li>An optional pipeline must be assigned to a unique and
+ non-empty filter expression.</li>
+
+ <li>Different pipeline steps can refer to the same
+ action.</li>
+
+ <li>Different pipelines can have different sets of steps
+ and different orders of steps.</li>
+
+ <li>Each pipeline step can be supplied with a unique
+ parameter.</li>
+ </ul>
+
+ <p class="backtotop"><a href="#top">Back to Top</a></p>
+
+ <h2><a id="Pipeline_Life-Cycle"
+ name="Pipeline_Life-cycle"></a>2.3 Pipeline Life-cycle</h2>
+
+ <h3><a id="Initialization"
+ name="Initialization"></a>2.3.1 Initialization</h3>
+
+ <p>The common pipeline is created at the JIT initialization.
+ All other pipelines are created just before their first use.
+ Therefore, an optional pipeline is only initialized when a
+ compiled method matches its filter.</p>
+
+ <p>During pipeline creation, the compiler iterates over all its
+ steps. For each step, the compiler creates an instance of the
+ referenced <code>Action</code> object and calls the
+ <code>Action::init() method</code>. At this point, all action
+ parameters are available and the <code>Action::init()</code>
+ method can use any of the <code>IAction::getArg</code> methods
+ to retrieve action parameters. For efficiency purposes,
+ parameters should be processed at the initialization phase, not
+ during compilation of each method.</p>
+
+ <p class="note">Note</p>
+
+ <p class="notetext">You can call the
+ <code>IAction::getArg</code> method from
+ <code>SessionAction::run()</code> during compilation of a
+ method, but it is a less effective way of parameter processing.
+ The SessionAction object has access to its parent
+ <code>Action</code> object and therefore, can access data
+ prepared during the initialization phase.</p>
+
+ <h3><a id="Method_Compilation"
+ name="Method_Compilation"></a>2.3.2 Method Compilation</h3>
+
+ <p>At this stage, the compiler selects the pipeline for the
+ given method using the filter expression in the method filter
+ and proceeds to compile a method. If the method matches several
+ filters, then the pipeline with the longest filter expression
+ is selected, that is PMF always chooses the filter with more
+ characters in its expression. PMF prohibits creation of
+ different pipelines with the same filter expression.</p>
+
+ <p>To compile the method, JIT executes the selected pipeline:
+ iterates over all its steps, creates a
+ <code>SessionAction</code> object for each step, calls the
+ <code>run()</code> method in each object, and destroys it.</p>
+
+ <h3><a id="De-initialization"
+ name="De-initialization"></a>2.3.3 De-initialization</h3>
+
+ <p>At the JIT de-initialization phase all created pipelines are
+ destroyed. The <code>Action::deinit()</code> method is called
+ for every step in a pipeline during its de-initialization.</p>
+
+ <p class="backtotop"><a href="#top">Back to Top</a></p>
+
+ <h1><a id="Command-line_Interface"
+ name="Command-line_Interface"></a>3. Command-line
+ Interface</h1>
+
+ <p>The <i>command-line interface</i> is based on system
+ properties defined by "property = value" relations. At the
+ initialization phase, all properties are stored in the table of
+ VM properties. Depending on the configuration mode, VM can
+ create several JITs. In this case, each JIT reads this table
+ and selects properties independently; therefore, different JITs
+ have different property sets.</p>
+
+ <p>The general form of the JIT command is the following:</p>
+ <pre>
+-Djit.<<b>JIT</b>>.<<b>pipeline</b>>.<<b>parameter</b>>=<<b>value</b>>
+</pre>
+
+ <p>Where</p>
+
+ <ul>
+ <li>
+ <code>-Djit.</code> is the mandatory prefix enabling
+ JIT commands selection from VM commands.
+
+ <p class="note">Note</p>
+
+ <p class="notetext">The Jitrino command-line interface
+ ignores all commands that do not start with this
+ prefix.</p>
+ </li>
+
+ <li>
+ <code><<b>JIT</b>></code> specifies the JIT name.
+
+
+ <p class="note">Note</p>
+
+ <p class="notetext">JITs are created by
+ <a href="#EM.html">Execution Manager</a> (EM) using
+ information from the command line and/or
+ <a href="http://incubator.apache.org/harmony/subcomponents/drlvm/emguide.html">
+ <code>execution manager configuration</code>
+ file</a>.</p>
+ </li>
+
+ <li><code><<b>pipeline</b>></code> specifies the
+ pipeline name.</li>
+
+ <li><code><<b>parameter</b>></code> and
+ <code><<b>value</b>></code> are used to construct one
+ of the three available basic commands:
+ <a href="#Filter_Definition">filter definition</a>,
+ <a href="#Path_Definition">path definition</a> and
+ <a href="#Argument_Definition">argument
+ definition</a>.</li>
+ </ul>
+
+ <p>Both <code><<b>JIT</b>></code> and
+ <code><<b>pipeline</b>></code> elements define the
+ command scope in the following way:</p>
+
+ <ul>
+ <li>If the <code><<b>JIT</b>></code> element is
+ omitted, the scope of the command consists of all existing
+ JITs.</li>
+
+ <li>If the <code><<b>pipeline</b>></code> element is
+ omitted, the scope of the command consists of all pipelines
+ existing in the specified JIT.</li>
+
+ <li>If both <code><<b>JIT</b>></code> and
+ <code><<b>pipeline</b>></code> are omitted, the scope
+ of the command consists of all pipelines of all JITs.<br />
+ <br /></li>
+ </ul>
+
+ <p>Commands can be specified on the command line or in the EM
+ configuration file. Most important commands are usually placed
+ in the
+ <a href="http://incubator.apache.org/harmony/subcomponents/drlvm/emguide.html">
+ <code>EM configuration</code> file</a>, so Jitrino can be used
+ without any commands on the command line.</p>
+
+ <p>The order of commands on the command line and in the
+ external file is not significant.</p>
+
+ <p>Another way to deal with a set of commands is to store it in
+ a <i>command file</i> and read this file with a special <i>read
+ command</i>:</p>
+ <pre>
+-Djit.read=<<b>command filename</b>>
+</pre>
+
+ <p class="note">Note</p>
+
+ <p class="notetext">Write commands in the command file without
+ the prefix <code>-Djit</code>. The <code>read</code> command
+ itself can be used in the command file. The command file can
+ contain empty lines and comment lines starting with
+ <code>#</code> or <code>//</code>.</p>
+
+ <p>For information on the general command line syntax
+ specification, refer to the
+ <a href="#Appendix">Appendix</a>.</p>
+
+ <p class="backtotop"><a href="#top">Back to Top</a></p>
+
+ <h1><a id="PMF_Commands"
+ name="PMF_Commands"></a>4. PMF Commands</h1>
+
+ <p>To control the JIT compilation process, PMF uses
+ <a href="#Path_Definition">path definition</a>,
+ <a href="#Filter_Definition">filter definition</a> and
+ <a href="#Argument_definition">argument definition</a>
+ commands.</p>
+
+ <h2><a id="Path_Definition"
+ name="Path_Definition"></a>4.1 Path Definition</h2>
+
+ <p>A pipeline can be described as an ordered set of terminal
+ leafs of a path tree. The tree is a purely abstract concept
+ introduced to describe the pipeline construction process. Each
+ non-terminal node of the tree is called a <i>path</i> and
+ defined by the following <i>path definition</i> command:</p>
+ <pre>
+-Djit.<<b>JIT</b>>.<<b>pipeline</b>>.path.<<b>name</b>>=<<b>child1</b>>,<<b>child2</b>>,...
+</pre>
+
+ <p>The given command introduces a node with the specified name
+ and enumerates all its direct descendants - children. If a
+ child is a terminal node, it is treated as the name of the
+ action; if not, then the child must be another path.</p>
+
+ <p>For each pipeline, define one path with the
+ <<b>name</b>> element omitted, which is called the
+ <i>root path</i>. Each path must have a unique definition.</p>
+
+ <p>Each action in the pipeline has a unique <i>full name</i>
+ consisting of all node names from the root to the action
+ itself. The root node is excluded because it has no name. More
+ than one instance of the same action can exist, as long as each
+ instance has a unique full name.</p>
+
+ <p class="example">Example</p>
+
+ <p class="exampletext"><code><b>OPT</b></code> is the JIT name
+ and <code><b>a</b></code>, <code><b>b</b></code> and
+ <code><b>c</b></code> are the action names.</p>
+ <pre>
+-Djit.OPT.path=M,N
+-Djit.OPT.path.M=a
+-Djit.OPT.path.N=b,c
+</pre>
+
+ <p class="exampletext">The given commands describe the simple
+ path tree:</p>
+
+ <p style="text-align: center"><img src="images/Pipeline1.png"
+ alt="package" /></p>
+
+ <p class="special">Figure 2: A Path Tree of a Common
+ Pipeline</p>
+
+ <p class="exampletext">The following resulting pipeline is
+ constructed from the aforementioned tree:<br />
+ <code><b>a</b></code>, <code><b>b</b></code>,
+ <code><b>c</b></code></p>
+
+ <p class="exampletext">The pipeline above is common, because it
+ has no method filter. Each action of the given pipeline has a
+ unique full name.</p>
+
+ <table width="31%"
+ height="161"
+ cellpadding="0">
+ <tr>
+ <th class="TableHeading">Action</th>
+
+ <th class="TableHeading">Full Name</th>
+ </tr>
+
+ <tr>
+ <td class="TableCell">a</td>
+
+ <td class="TableCell">M.a</td>
+ </tr>
+
+ <tr>
+ <td width="30%"
+ class="TableCell">b</td>
+
+ <td width="30%"
+ class="TableCell">N.b</td>
+ </tr>
+
+ <tr>
+ <td width="30%"
+ class="TableCell">c</td>
+
+ <td width="30%"
+ class="TableCell">N.c</td>
+ </tr>
+ </table>
+
+ <p class="backtotop"><a href="#top">Back to Top</a></p>
+
+ <h2><a id="Filter_Definition"
+ name="Filter_Definition"></a>4.2 Filter Definition</h2>
+
+ <p>To define a filter, use the following command format:</p>
+ <pre>
+-Djit.<<b>JIT</b>>.<<b>pipeline</b>>.filter=<<b>class</b>>.<<b>method</b>><<b>signature</b>>
+</pre>
+
+ <p>Where</p>
+
+ <ul>
+ <li><<code><b>pipeline</b></code>> is the required
+ element, which cannot be omitted.</li>
+
+ <li><<code><b>class</b></code>> is the name of the
+ class constituting the filter expression.</li>
+
+ <li><<code><b>method</b></code>> is the name of the
+ method constituting the filter expression.</li>
+
+ <li><<code><b>signature</b></code>> is the signature
+ of the method constituting the filter expression.</li>
+ </ul>
+
+ <p class="note">Note</p>
+
+ <p class="notetext">In the filter definition, the
+ <code>method</code> and the <code>signature</code> elements
+ have no period <code>.</code> between them.</p>
+
+ <p>You must follow the VM notation for the described elements.
+ You are free to omit some elements, but at least one must be
+ present.</p>
+
+ <p>If each of three elements of the method name starts with the
+ corresponding element of the filter expression, the compiled
+ method matches the filter.</p>
+
+ <p class="example">Example</p>
+ <pre>
+-Djit.OPT.p.filter=java/lang/Thread.check
+</pre>
+
+ <p class="exampletext">The following methods can match the
+ given filter:<br />
+ <code>java/lang/ThreadGroup.checkAccess()V</code><br />
+ <code>java/lang/Thread.checkGCWatermark()V</code><br />
+ <code>java/lang/Thread.checkAccess()V</code></p>
+
+ <p>To continue the example, methods can equally match a less
+ detailed filter expression, such as
+ <code>java/lang.check</code>. However, PMF would use the more
+ specific filter, as described in the
+ <a href="#Method_Compilation">Method Compilation</a>
+ section.</p>
+
+ <p class="example">Example</p>
+ <pre>
+-Djit.OPT.path=M,N
+-Djit.OPT.path.M=a
+-Djit.OPT.path.N=b,c
+-Djit.OPT.p.path=M,N,O
+-Djit.OPT.p.path.O=a
+-Djit.OPT.p.filter=java/lang/Thread.check
+</pre>
+
+ <p class="exampletext">The commands above are associated with
+ the following path trees:</p>
+
+ <p style="text-align: center"><img src="images/Pipelines2.png"
+ alt="package" /></p>
+
+ <p class="special">Figure 3: An Example of Path Trees for
+ Multiple Pipelines</p>
+
+ <p class="exampletext">The following resulting pipelines are
+ constructed from the aforementioned trees:<br />
+ (<code>common</code>) <code><b>a</b></code>,
+ <code><b>b</b></code>, <code><b>c</b></code><br />
+ (<code>p</code>)
+ <code><b>a</b></code>, <code><b>b</b></code>,
+ <code><b>c</b></code>, <code><b>a</b></code></p>
+
+ <p class="note">Note</p>
+
+ <p class="notetext">Path definitions <code><b>M</b></code> and
+ <code><b>N</b></code> in the pipeline <code><b>p</b></code> are
+ inherited from the common pipeline, because they were defined
+ in commands with the pipeline element omitted, but the root
+ path definition in the <code><b>p</b></code> pipeline was
+ overridden.</p>
+
+ <p class="backtotop"><a href="#top">Back to Top</a></p>
+
+ <h2><a id="Argument_Definition"
+ name="Argument_Definition"></a>4.3 Argument Definition</h2>
+
+ <p>To control the actions behavior, PMF supports an action
+ parameters passing convention. The parameter definition command
+ pattern is the following:</p>
+ <pre>
+-Djit.<<b>JIT</b>>.<<b>pipeline</b>>.arg.<<b>full name</b>>.<<b>param</b>>=<<b>value</b>>
+</pre>
+
+ <p>Where</p>
+
+ <ul>
+ <li><<b>param</b>> and <<b>value</b>> are
+ mandatory elements.</li>
+
+ <li><<b>JIT</b>>, <<b>pipeline</b>> and
+ <<b>full name</b>> are optional elements defining the
+ scope of the both.</li>
+ </ul>
+
+ <p>The <<b>full name</b>> element defines the parameter
+ scope in the following way:</p>
+
+ <ul>
+ <li>If <<b>full name</b>> addresses a certain action,
+ that is a terminal node, the parameter affects all
+ instances of this action.</li>
+
+ <li>If <<b>full name</b>> addresses not an action,
+ but a node with children, the parameter affects this node
+ and all its descendants.</li>
+
+ <li>If <<b>full name</b>> is omitted, the parameter
+ affects all actions in the pipeline.</li>
+ </ul>
+
+ <p class="example">Example</p>
+ <pre>
+-Djit.OPT.p.arg.a.verify=1
+</pre>
+
+ <p class="exampletext">The given command sets the
+ <<b>verify</b>> parameter for both <code><b>a</b></code>
+ instances, <code><b>M.a</b></code> and <code><b>O.a</b></code>,
+ to <b>1</b>. See Figure 3.</p>
+
+ <p>The table below gives several examples of essential commands
+ for the path trees based on Figure 3.</p>
+
+ <table>
+ <tr>
+ <th width="232"
+ class="TableHeading">Command</th>
+
+ <th width="98"
+ class="TableHeading">Omitted Element</th>
+
+ <th width="631"
+ class="TableHeading">Definition</th>
+ </tr>
+
+ <tr>
+ <td class="TableCell">
+ <code>-Djit.OPT.p.arg.N.b.verify=2</code></td>
+
+ <td class="TableCell">
+ <center>
+ —
+ </center>
+ </td>
+
+ <td class="TableCell">The parameter <code>verify</code>
+ with value 2 is available only to action
+ <code><b>b</b></code> with the full name
+ <code><b>N.b</b></code> in pipeline
+ <code><b>p</b></code> of JIT
+ <code><b>OPT</b></code>.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell">
+ <code>-Djit.OPT.p.arg.N.verify=2</code></td>
+
+ <td class="TableCell">
+ <center>
+ —
+ </center>
+ </td>
+
+ <td class="TableCell">The parameter <code>verify</code>
+ is available for actions <code><b>b</b></code> and
+ <code><b>c</b></code> simultaneously.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell">
+ <code>-Djit.OPT.p.arg.verify=2</code></td>
+
+ <td class="TableCell"><code><<b>full
+ name</b>></code></td>
+
+ <td class="TableCell">The parameter <code>verify</code>
+ is available for all actions <code><b>a</b></code>,
+ <code><b>b</b></code>, <code><b>c</b></code> and
+ <code><b>a</b></code> in pipeline
+ <code><b>p</b></code>.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell">
+ <code>-Djit.OPT.arg.N.verify=2</code></td>
+
+ <td class="TableCell">
+ <code><<b>pipeline</b>></code></td>
+
+ <td class="TableCell">The parameter <code>verify</code>
+ is available for <code><b>b</b></code> and
+ <code><b>c</b></code> actions for common and
+ <code><b>p</b></code> pipelines of JIT
+ <code><b>OPT</b></code> .</td>
+ </tr>
+ </table>
+
+ <p>The special form of argument definition commands controls
+ the pipeline construction process:</p>
+ <pre>
+-Djit.<<b>JIT</b>>.<<b>pipeline</b>>.arg.<<b>full name</b>>=on
+-Djit.<<b>JIT</b>>.<<b>pipeline</b>>.arg.<<b>full name</b>>=off
+</pre>
+
+ <p class="note">Note</p>
+
+ <p class="notetext">In the given form of the argument
+ definition, the <<b>param</b>> element is absent and only
+ two values for <<b>value</b>> exist: <code>on</code> and
+ <code>off</code>.</p>
+
+ <p>The <code>off</code> value disables the addressed node and
+ all its descendants, while the <code>on</code> value enables
+ the node and its descendants. When constructed, a pipeline does
+ not include any disabled actions.</p>
+
+ <p class="example">Example</p>
+
+ <p class="exampletext">To exclude action <code><b>b</b></code>
+ from the pipeline, apply the following command:</p>
+ <pre>
+-Djit.OPT.p.arg.N.b=off
+</pre>
+
+ <p>To enable/disable nodes directly in the path definition
+ command, add state characters immediately after the node name,
+ videlicet:</p>
+
+ <table width="53%"
+ height="161"
+ cellpadding="0">
+ <tr>
+ <th class="TableHeading">Character</th>
+
+ <th class="TableHeading">Corresponding Node
+ Meaning</th>
+ </tr>
+
+ <tr>
+ <td class="TableCell">
+ <center>
+ +
+ </center>
+ </td>
+
+ <td class="TableCell">enabled</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell">
+ <center>
+ —
+ </center>
+ </td>
+
+ <td class="TableCell">disabled</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell">
+ <center>
+ !
+ </center>
+ </td>
+
+ <td class="TableCell">cannot be disabled</td>
+ </tr>
+ </table>
+
+ <p>The following command states that <code>c1</code> is
+ enabled, <code>c2</code> is disabled and <code>c3</code> is
+ enabled and mandatory:</p>
+ <pre>
+-Djit.<<b>JIT</b>>.<<b>pipeline</b>>.path.<<b>name</b>>=c1+,c2-,c3!
+</pre>
+
+ <p>If you try to disable any mandatory node with the
+ <code>off</code> command, the fatal error occurs.</p>
+
+ <p class="backtotop"><a href="#top">Back to Top</a></p>
+
+ <h1><a id="Logging_System"
+ name="Logging_System"></a>5. Logging System</h1>
+
+ <p>The <i>logging system</i> supports diagnostic messages from
+ pipeline actions. The VM property mechanism fully controls the
+ system.</p>
+
+ <h2><a id="Stream_Definition"
+ name="Defining_Streams"></a>5.1 Defining Streams</h2>
+
+ <p>A set of <i>log streams</i> is used for logging in Jitrino.
+ Each log stream has a name. The name of the log stream is not
+ related to the name of the file, to which the stream is
+ assigned. The class <code>Jitrino::LogStream</code> is the
+ program representation of a log stream. This class is similar
+ to the <code>std::ostream</code> class in the defining operator
+ <code><<</code> and other useful methods, such as
+ <code>printf()</code> and <code>flush()</code>. To obtain the
+ reference to the underlying <code>std::ostream</code> instance,
+ call the <code>out()</code> method.</p>
+
+ <p>Streams can be accessed by name or by ID. The stream ID can
+ be obtained from its name by using the
+ <code>IAction::getLogStreamID()</code> method. For performance
+ reasons, several most frequently used streams, so-called
+ <i>known</i> streams, have predefined IDs:</p>
+
+ <table>
+ <tr>
+ <th class="TableHeading">Stream Name</th>
+
+ <th class="TableHeading">Stream ID</th>
+
+ <th class="TableHeading">Output</th>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>info</code></td>
+
+ <td class="TableCell"><code>LogStream::INFO</code></td>
+
+ <td class="TableCell">The protocol of compilation: JIT
+ and pipeline names, the method name and number, and so
+ on.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>rt</code></td>
+
+ <td class="TableCell"><code>LogStream::RT</code></td>
+
+ <td class="TableCell">Run-time output not related to
+ compiled methods.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>ct</code></td>
+
+ <td class="TableCell"><code>LogStream::CT</code></td>
+
+ <td class="TableCell">Compile-time diagnostic.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>irdump</code></td>
+
+ <td class="TableCell">
+ <code>LogStream::IRDUMP</code></td>
+
+ <td class="TableCell">The dump of internal Jitrino
+ structures for a compiled method.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>dotdump</code></td>
+
+ <td class="TableCell">
+ <code>LogStream::DOthUMP</code></td>
+
+ <td class="TableCell">The dump of internal Jitrino
+ structures in the <code>.dot</code> format.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>dbg</code></td>
+
+ <td class="TableCell"><code>LogStream::DBG</code></td>
+
+ <td class="TableCell">Debug information.</td>
+ </tr>
+ </table>
+
+ <p>To enable outputting log information to a stream, enter a
+ command of the following syntax:</p>
+ <pre>
+-Djit.<<b>JIT</b>>.<<b>pipeline</b>>.arg.<<b>full name</b>>.log=<<b>stream1</b>>,<<b>stream2</b>>,...
+</pre>
+
+ <p>The left part of the command specifies the name of the JIT
+ compiler and the compilation pipeline to be used, whereas the
+ right part contains the names of the streams that you want to
+ enable. Use the same syntax to enable a custom stream: write an
+ arbitrary name for it and enable the stream with this
+ command.</p>
+
+ <p class="note">Note</p>
+
+ <p class="notetext">If program output is directed to a disabled
+ stream, the output is lost and no error diagnostic is
+ produced.</p>
+
+ <p>The enabling command follows the general scope of rules: the
+ stream is enabled for the node specified in the command and all
+ its descendants.</p>
+
+ <p>Streams defined for different nodes are different streams,
+ though they can have the same name.</p>
+
+ <p class="example">Example</p>
+
+ <p class="exampletext">The following commands enable two
+ different streams, though both can be accessed from actions
+ <code><b>N.b</b></code> and <code><b>N.c</b></code> by the same
+ name. The streams can be assigned to different files.</p>
+ <pre>
+-Djit.OPT.p.arg.N.b.log=ct
+-Djit.OPT.p.arg.N.c.log=ct
+</pre>
+
+ <p class="backtotop"><a href="#top">Back to Top</a></p>
+
+ <h2><a id="Assigning_a_Stream_to_a_File"
+ name="Assigning_a_Stream_to_a _File"></a>5.2 Assigning a
+ Stream to a File</h2>
+
+ <p>To assign a stream to a file, use the following command
+ syntax:</p>
+ <pre>
+-Djit.<<b>JIT</b>>.<<b>pipeline</b>>.arg.<<b>full name</b>>.log.<<b>stream</b>>.file=<<b>filename mask</b>>
+</pre>
+
+ <p>In the given command, the <<b>filename mask</b>>
+ element constructs a filename for the stream. All characters
+ from this mask are copied to the resulting filename literally
+ except macros, which are expanded and the result of expansion
+ is copied to the filename. Below is the list of available
+ macros.</p>
+
+ <table>
+ <tr>
+ <th class="TableHeading">Macro</th>
+
+ <th class="TableHeading">Expands To</th>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>%jit%</code></td>
+
+ <td class="TableCell">The name of the JIT that is
+ compiling the method.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>%class%</code></td>
+
+ <td class="TableCell">The method class name with
+ <code>/</code> changed to <code>_</code></td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>%class_tree%</code></td>
+
+ <td class="TableCell">The method class name with
+ <code>/</code> preserved.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>%method%</code></td>
+
+ <td class="TableCell">The method name and signature in
+ VM notation.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>%seqnb%</code></td>
+
+ <td class="TableCell">The global sequential number of
+ the current compilation.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>%log%</code></td>
+
+ <td class="TableCell">The name of the stream.</td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>%thread%</code></td>
+
+ <td class="TableCell">The number of the thread
+ compiling the method.</td>
+ </tr>
+ </table>
+
+ <p>In most cases, a program can access the stream file from
+ concurrent threads, so that all stream operations are
+ synchronized. However, if a filename mask for the stream
+ contains the <code>%thread%</code> macro, this file is
+ thread-specific and access to it is not synchronized.</p>
+
+ <h3><a id="Using_File-name_Masks"
+ name="Using_Filename_Masks"></a>5.2.1 Using Filename
+ Masks</h3>
+
+ <p>For all streams, the following default filename mask is
+ used:</p>
+ <pre>
+log/%jit%/%class%/%method%/%log%.log
+</pre>
+
+ <p>For example, for an enabled stream <code>abc</code> with no
+ assigned filename mask, the log file is in the same directory
+ with other known stream files, and its name is
+ <code>abc.log</code>.</p>
+
+ <p>All known streams have hard-coded default filename masks,
+ described in the table below. These masks are used if no
+ assignment is made with the corresponding command.</p>
+
+ <table width="451">
+ <tr>
+ <th width="110"
+ class="TableHeading">Stream Name</th>
+
+ <th width="298"
+ class="TableHeading">Default Filename Mask</th>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>info</code></td>
+
+ <td class="TableCell"><code>log/info.log</code></td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>rt</code></td>
+
+ <td class="TableCell"><code>log/rt.log</code></td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>ct</code></td>
+
+ <td class="TableCell">
+ <code>log/%jit%/%class%/%method%/ct.log</code></td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>irdump</code></td>
+
+ <td class="TableCell">
+ <code>log/%jit%/%class%/%method%/ct.log</code></td>
+ </tr>
+
+ <tr>
+ <td class="TableCell"><code>dotdump</code></td>
+
+ <td class="TableCell">
+ <code>log/%jit%/%class%/%method%/.dot [special
+ case]</code></td>
+ </tr>
+ </table>
+
+ <p class="example">Exception</p>
+
+ <p class="exampletext">Jitrino writes dot-dumps to the
+ <code>dotdump</code> stream and produces two <code>.dot</code>
+ files for each action: <i>before</i> and <i>after</i> execution
+ of an action. To handle these correctly, the enabled dot-dumper
+ opens the <code>dotdump</code> stream before executing the
+ action, writes to the stream and closes it. After executing the
+ action, the dot-dumper performs the same operation. Each time,
+ the dot-dumper adds a suffix that indicates the sequence of
+ actions to the tail of the stream filename <code>.dot</code>,
+ as follows:</p>
+ <pre>
+ .<<b>action_nb</b>>.<<b>action_name</b>>.before.dot
+ .<<b>action_nb</b>>.<<b>action_name</b>>.after.dot
+</pre>
+
+ <p>In the command above, the <<b>action name</b>> element
+ is the name of the action and <<b>action_nb</b>> is the
+ sequential number of the action in the current pipeline.</p>
+
+ <h3><a id="File_Name_Review"
+ name="Filename_Review"></a>5.2.2 Filename Review</h3>
+
+ <p>Names of all open stream files are reviewed at the beginning
+ of method compilation, because the stream file name can depend
+ on the name of the compiled method. If the name is changed as
+ the result of the dependency on the compiled method name, the
+ file is closed and another file with the new calculated name is
+ opened. If the name is not changed, no action is performed. If
[... 111 lines stripped ...]