profile.html

perl教程

</dl>
<p>
</p>
<hr />
<h1><a name="enabling_a_profile">ENABLING A PROFILE</a></h1>
<p>Profiling is enabled for a handle by assigning to the Profile
attribute. For example:</p>
<pre>
  <span class="variable">$h</span><span class="operator">-&gt;</span><span class="operator">{</span><span class="string">Profile</span><span class="operator">}</span> <span class="operator">=</span> <span class="variable">DBI::Profile</span><span class="operator">-&gt;</span><span class="variable">new</span><span class="operator">();</span>
</pre>
<p>The Profile attribute holds a blessed reference to a hash object
that contains the profile data and attributes relating to it.</p>
<p>The class the Profile object is blessed into is expected to
provide at least a DESTROY method which will dump the profile data
to the DBI trace file handle (STDERR by default).</p>
<p>All these examples have the same effect as each other:</p>
<pre>
  <span class="variable">$h</span><span class="operator">-&gt;</span><span class="operator">{</span><span class="string">Profile</span><span class="operator">}</span> <span class="operator">=</span> <span class="number">0</span><span class="operator">;</span>
  <span class="variable">$h</span><span class="operator">-&gt;</span><span class="operator">{</span><span class="string">Profile</span><span class="operator">}</span> <span class="operator">=</span> <span class="string">"/DBI::Profile"</span><span class="operator">;</span>
  <span class="variable">$h</span><span class="operator">-&gt;</span><span class="operator">{</span><span class="string">Profile</span><span class="operator">}</span> <span class="operator">=</span> <span class="variable">DBI::Profile</span><span class="operator">-&gt;</span><span class="variable">new</span><span class="operator">();</span>
  <span class="variable">$h</span><span class="operator">-&gt;</span><span class="operator">{</span><span class="string">Profile</span><span class="operator">}</span> <span class="operator">=</span> <span class="operator">{}</span><span class="operator">;</span>
  <span class="variable">$h</span><span class="operator">-&gt;</span><span class="operator">{</span><span class="string">Profile</span><span class="operator">}</span> <span class="operator">=</span> <span class="operator">{</span> <span class="string">Path</span> <span class="operator">=&gt;</span> <span class="operator">[]</span> <span class="operator">}</span><span class="operator">;</span>
</pre>
<p>Similarly, these examples have the same effect as each other:</p>
<pre>
  <span class="variable">$h</span><span class="operator">-&gt;</span><span class="operator">{</span><span class="string">Profile</span><span class="operator">}</span> <span class="operator">=</span> <span class="number">6</span><span class="operator">;</span>
  <span class="variable">$h</span><span class="operator">-&gt;</span><span class="operator">{</span><span class="string">Profile</span><span class="operator">}</span> <span class="operator">=</span> <span class="string">"6/DBI::Profile"</span><span class="operator">;</span>
  <span class="variable">$h</span><span class="operator">-&gt;</span><span class="operator">{</span><span class="string">Profile</span><span class="operator">}</span> <span class="operator">=</span> <span class="string">"!Statement:!MethodName/DBI::Profile"</span><span class="operator">;</span>
  <span class="variable">$h</span><span class="operator">-&gt;</span><span class="operator">{</span><span class="string">Profile</span><span class="operator">}</span> <span class="operator">=</span> <span class="operator">{</span> <span class="string">Path</span> <span class="operator">=&gt;</span> <span class="operator">[</span> <span class="string">'!Statement'</span><span class="operator">,</span> <span class="string">'!MethodName'</span> <span class="operator">]</span> <span class="operator">}</span><span class="operator">;</span>
</pre>
<p>If a non-blessed hash reference is given then the DBI::Profile
module is automatically <a href="../../lib/Pod/perlfunc.html#item_require"><code>require</code></a>'d and the reference is blessed
into that class.</p>
<p>If a string is given then it is processed like this:</p>
<pre>
    ($path, $module, $args) = split /\//, $string, 3</pre>
<pre>
    @path = split /:/, $path
    @args = split /:/, $args</pre>
<pre>
    eval &quot;require $module&quot; if $module
    $module ||= &quot;DBI::Profile&quot;</pre>
<pre>
    $module-&gt;new( Path =&gt; \@Path, @args )</pre>
<p>So the first value is used to select the Path to be used (see below).
The second value, if present, is used as the name of a module which
will be loaded and it's <code>new</code> method called. If not present it
defaults to DBI::Profile. Any other values are passed as arguments
to the <code>new</code> method. For example: &quot;<code>2/DBIx::OtherProfile/Foo:42</code>&quot;.</p>
<p>Numbers can be used as a shorthand way to enable common Path values.
The simplest way to explain how the values are interpreted is to show the code:</p>
<pre>
    <span class="keyword">push</span> <span class="variable">@Path</span><span class="operator">,</span> <span class="string">"DBI"</span>           <span class="keyword">if</span> <span class="variable">$path_elem</span> <span class="operator">&amp;</span> <span class="number">0x01</span><span class="operator">;</span>
    <span class="keyword">push</span> <span class="variable">@Path</span><span class="operator">,</span> <span class="string">"!Statement"</span>    <span class="keyword">if</span> <span class="variable">$path_elem</span> <span class="operator">&amp;</span> <span class="number">0x02</span><span class="operator">;</span>
    <span class="keyword">push</span> <span class="variable">@Path</span><span class="operator">,</span> <span class="string">"!MethodName"</span>   <span class="keyword">if</span> <span class="variable">$path_elem</span> <span class="operator">&amp;</span> <span class="number">0x04</span><span class="operator">;</span>
    <span class="keyword">push</span> <span class="variable">@Path</span><span class="operator">,</span> <span class="string">"!MethodClass"</span>  <span class="keyword">if</span> <span class="variable">$path_elem</span> <span class="operator">&amp;</span> <span class="number">0x08</span><span class="operator">;</span>
    <span class="keyword">push</span> <span class="variable">@Path</span><span class="operator">,</span> <span class="string">"!Caller2"</span>      <span class="keyword">if</span> <span class="variable">$path_elem</span> <span class="operator">&amp;</span> <span class="number">0x10</span><span class="operator">;</span>
</pre>
<p>So &quot;2&quot; is the same as &quot;!Statement&quot; and &quot;6&quot; (2+4) is the same as
&quot;!Statement:!Method&quot;.  Those are the two most commonly used values.  Using a
negative number will reverse the path. Thus &quot;-6&quot; will group by method name then
statement.</p>
<p>The spliting and parsing of string values assigned to the Profile
attribute may seem a little odd, but there's a good reason for it.
Remember that attributes can be embedded in the Data Source Name
string which can be passed in to a script as a parameter. For
example:</p>
<pre>
    <span class="variable">dbi</span><span class="operator">:</span><span class="variable">DriverName</span><span class="operator">(</span><span class="string">Profile</span><span class="operator">=&gt;</span><span class="number">2</span><span class="operator">):</span><span class="variable">dbname</span>
    <span class="variable">dbi</span><span class="operator">:</span><span class="variable">DriverName</span><span class="operator">(</span><span class="string">Profile</span><span class="operator">=&gt;</span><span class="operator">{</span><span class="string">Username</span><span class="operator">}</span><span class="operator">:!</span><span class="variable">Statement</span><span class="operator">/</span><span class="variable">MyProfiler</span><span class="operator">/</span><span class="variable">Foo</span><span class="operator">:</span><span class="number">42</span><span class="operator">):</span><span class="variable">dbname</span>
</pre>
<p>And also, if the <code>DBI_PROFILE</code> environment variable is set then
The DBI arranges for every driver handle to share the same profile
object. When perl exits a single profile summary will be generated
that reflects (as nearly as practical) the total use of the DBI by
the application.</p>
<p>
</p>
<hr />
<h1><a name="the_profile_object">THE PROFILE OBJECT</a></h1>
<p>The DBI core expects the Profile attribute value to be a hash
reference and if the following values don't exist it will create
them as needed:</p>
<p>
</p>
<h2><a name="data">Data</a></h2>
<p>A reference to a hash containing the collected profile data.</p>
<p>
</p>
<h2><a name="path">Path</a></h2>
<p>The Path value is a reference to an array. Each element controls the
value to use at the corresponding level of the profile Data tree.</p>
<p>The elements of Path array can be one of the following types:</p>
<dl>
<dt><strong><a name="item_special_constant">Special Constant</a></strong>

<dd>
<p><strong>!Statement</strong></p>
</dd>
<dd>
<p>Use the current Statement text. Typically that's the value of the Statement
attribute for the handle the method was called with. Some methods, like
<code>commit()</code> and rollback(), are unrelated to a particular statement. For those
methods !Statement records an empty string.</p>
</dd>
<dd>
<p>For statement handles this is always simply the string that was
given to <code>prepare()</code> when the handle was created.  For database handles
this is the statement that was last prepared or executed on that
database handle. That can lead to a little 'fuzzyness' because, for
example, calls to the <code>quote()</code> method to build a new statement will
typically be associated with the previous statement. In practice
this isn't a significant issue and the dynamic Path mechanism can
be used to setup your own rules.</p>
</dd>
<dd>
<p><strong>!MethodName</strong></p>
</dd>
<dd>
<p>Use the name of the DBI method that the profile sample relates to.</p>
</dd>
<dd>
<p><strong>!MethodClass</strong></p>
</dd>
<dd>
<p>Use the fully qualified name of the DBI method, including
the package, that the profile sample relates to. This shows you
where the method was implemented. For example:</p>
</dd>
<dd>
<pre>
  'DBD::_::db::selectrow_arrayref' =&gt;
      0.022902s
  'DBD::mysql::db::selectrow_arrayref' =&gt;
      2.244521s / 99 = 0.022445s avg (first 0.022813s, min 0.022051s, max 0.028932s)</pre>
</dd>
<dd>
<p>The &quot;DBD::_::db::selectrow_arrayref&quot; shows that the driver has
inherited the selectrow_arrayref method provided by the DBI.</p>
</dd>
<dd>
<p>But you'll note that there is only one call to
DBD::_::db::selectrow_arrayref but another 99 to
DBD::mysql::db::selectrow_arrayref. Currently the first
call Pern't record the true location. That may change.</p>
</dd>
<dd>
<p><strong>!Caller</strong></p>
</dd>
<dd>
<p>Use a string showing the filename and line number of the code calling the method.</p>
</dd>
<dd>
<p><strong>!Caller2</strong></p>
</dd>
<dd>
<p>Use a string showing the filename and line number of the code calling the
method, as for !Caller, but also include filename and line number of the code
that called that. Calls from DBI:: and DBD:: packages are skipped.</p>
</dd>
<dd>
<p><strong>!File</strong></p>
</dd>
<dd>
<p>Same as !Caller above except that only the filename is included, not the line number.</p>
</dd>
<dd>
<p><strong>!File2</strong></p>
</dd>
<dd>
<p>Same as !Caller2 above except that only the filenames are included, not the line number.</p>
</dd>
</li>
<dt><strong><a name="item_code_reference">Code Reference</a></strong>

<dd>
<p>Not yet implemented.</p>
</dd>
<dd>
<p>The subroutine is passed the DBI method name and the handle it was called on.
It should return a list of values to used at this point in the Path.  If it
returns an empty list then the method call is not profiled.</p>
</dd>
</li>
<dt><strong><a name="item_attribute_specifier">Attribute Specifier</a></strong>

<dd>
<p>A string enclosed in braces, such as '<code>{Username}</code>', specifies that the current
value of the corresponding database handle attribute should be used at that
point in the Path.</p>
</dd>
</li>
<dt><strong><a name="item_other_values">Other Values</a></strong>

<dd>
<p>Any other values are stringified and used literally.</p>
</dd>
<dd>
<p>(References, and values that begin with punctuation characters are reserved.)</p>
</dd>
</li>
</dl>
<p>Only the first 100 elements in Path are used.</p>
<p>If the value of Path is anything other than an array reference,
it is treated as if it was:</p>
<pre>
        [ DBI::Profile::!Statement ]</pre>
<p>
</p>
<hr />
<h1><a name="reporting">REPORTING</a></h1>
<p>
</p>
<h2><a name="report_format">Report Format</a></h2>
<p>The current accumulated profile data can be formatted and output using</p>
<pre>