You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by na...@apache.org on 2007/03/13 13:17:45 UTC
svn commit: r517663 [13/14] - in /harmony/standard/site: docs/
docs/documentation/ docs/subcomponents/classlibrary/
docs/subcomponents/drlvm/ xdocs/ xdocs/documentation/ xdocs/stylesheets/
xdocs/subcomponents/classlibrary/ xdocs/subcomponents/drlvm/
Modified: 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=diff&rev=517663&r1=517662&r2=517663
==============================================================================
--- harmony/standard/site/xdocs/subcomponents/drlvm/Jitrino_PMF.html (original)
+++ harmony/standard/site/xdocs/subcomponents/drlvm/Jitrino_PMF.html Tue Mar 13 05:17:43 2007
@@ -1,1312 +1,1312 @@
-<!--
- Licensed to the Apache Software Foundation (ASF) under one or more
- contributor license agreements. See the NOTICE file distributed with
- this work for additional information regarding copyright ownership.
- The ASF licenses this file to You 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
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- 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.
--->
-
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<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="../../documentation/conventions.html">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="JIT.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>
--XDjit.<<b>JIT</b>>.<<b>pipeline</b>>.<<b>parameter</b>>=<<b>value</b>>
-</pre>
-
- <p>Where</p>
-
- <ul>
- <li>
- <code>-XDjit.</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>
--XDjit.read=<<b>command filename</b>>
-</pre>
-
- <p class="note">Note</p>
-
- <p class="notetext">Write commands in the command file without
- the prefix <code>-XDjit</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>
--XDjit.<<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>
--XDjit.OPT.path=M,N
--XDjit.OPT.path.M=a
--XDjit.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>
- <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
- class="TableCell">b</td>
-
- <td
- class="TableCell">N.b</td>
- </tr>
-
- <tr>
- <td
- class="TableCell">c</td>
-
- <td
- 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>
--XDjit.<<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>
--XDjit.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>
--XDjit.OPT.path=M,N
--XDjit.OPT.path.M=a
--XDjit.OPT.path.N=b,c
--XDjit.OPT.p.path=M,N,O
--XDjit.OPT.p.path.O=a
--XDjit.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>
--XDjit.<<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>
--XDjit.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
- class="TableHeading">Command</th>
-
- <th
- class="TableHeading">Omitted Element</th>
-
- <th width="631"
- class="TableHeading">Definition</th>
- </tr>
-
- <tr>
- <td class="TableCell">
- <code>-XDjit.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>-XDjit.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>-XDjit.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>-XDjit.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>
--XDjit.<<b>JIT</b>>.<<b>pipeline</b>>.arg.<<b>full name</b>>=on
--XDjit.<<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>
--XDjit.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>
- <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>
--XDjit.<<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
- 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>
--XDjit.<<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>
--XDjit.OPT.p.arg.N.b.log=ct
--XDjit.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>
--XDjit.<<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 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>
- <tr>
- <th class="TableHeading">Stream Name</th>
-
- <th
- 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 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>
--XDjit.<<b>JIT</b>>.<<b>pipeline</b>>.arg.<<b>full name</b>>.log.<<b>stream</b>>.append=true
--XDjit.<<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 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> : -XDjit.
-
-<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>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You 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
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ 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.
+-->
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<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="../../documentation/conventions.html">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="JIT.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>
+-XDjit.<<b>JIT</b>>.<<b>pipeline</b>>.<<b>parameter</b>>=<<b>value</b>>
+</pre>
+
+ <p>Where</p>
+
+ <ul>
+ <li>
+ <code>-XDjit.</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>
+-XDjit.read=<<b>command filename</b>>
+</pre>
+
+ <p class="note">Note</p>
+
+ <p class="notetext">Write commands in the command file without
+ the prefix <code>-XDjit</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>
+-XDjit.<<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>
+-XDjit.OPT.path=M,N
+-XDjit.OPT.path.M=a
+-XDjit.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>
+ <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
+ class="TableCell">b</td>
+
+ <td
+ class="TableCell">N.b</td>
+ </tr>
+
+ <tr>
+ <td
+ class="TableCell">c</td>
+
+ <td
+ 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>
+-XDjit.<<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>
+-XDjit.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>
+-XDjit.OPT.path=M,N
+-XDjit.OPT.path.M=a
+-XDjit.OPT.path.N=b,c
+-XDjit.OPT.p.path=M,N,O
+-XDjit.OPT.p.path.O=a
+-XDjit.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>
+-XDjit.<<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>
+-XDjit.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
+ class="TableHeading">Command</th>
+
+ <th
+ class="TableHeading">Omitted Element</th>
+
+ <th width="631"
+ class="TableHeading">Definition</th>
+ </tr>
+
+ <tr>
+ <td class="TableCell">
+ <code>-XDjit.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>-XDjit.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>-XDjit.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>-XDjit.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>
+-XDjit.<<b>JIT</b>>.<<b>pipeline</b>>.arg.<<b>full name</b>>=on
+-XDjit.<<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>
+-XDjit.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>
+ <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>
+-XDjit.<<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
+ 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>
+-XDjit.<<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>
+-XDjit.OPT.p.arg.N.b.log=ct
+-XDjit.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>
+-XDjit.<<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 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>
+ <tr>
+ <th class="TableHeading">Stream Name</th>
+
+ <th
+ 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>
+
[... 137 lines stripped ...]