dbi::profile.3

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

Here you can see the 'avg', 'first', 'min' and 'max' for the
108 calls to \fIfetchrow_hashref()\fR become rather more interesting.
Also the data for \s-1FETCH\s0 just shows a time value because it was only
called once.
.PP
Currently the profile data is output sorted by branch names. That
may change in a later version so the leaf nodes are sorted by total
time per leaf node.
.Sh "Report Destination"
.IX Subsection "Report Destination"
The default method of reporting is for the \s-1DESTROY\s0 method of the
Profile object to format the results and write them using:
.PP
.Vb 1
\&    DBI\->trace_msg($results, 0);  # see $ON_DESTROY_DUMP below
.Ve
.PP
to write them to the \s-1DBI\s0 \fItrace()\fR filehandle (which defaults to
\&\s-1STDERR\s0). To direct the \s-1DBI\s0 trace filehandle to write to a file
without enabling tracing the \fItrace()\fR method can be called with a
trace level of 0. For example:
.PP
.Vb 1
\&    DBI\->trace(0, $filename);
.Ve
.PP
The same effect can be achieved without changing the code by
setting the \f(CW\*(C`DBI_TRACE\*(C'\fR environment variable to \f(CW\*(C`0=filename\*(C'\fR.
.PP
The \f(CW$DBI::Profile::ON_DESTROY_DUMP\fR variable holds a code ref
that's called to perform the output of the formatted results.
The default value is:
.PP
.Vb 1
\&  $ON_DESTROY_DUMP = sub { DBI\->trace_msg($results, 0) };
.Ve
.PP
Apart from making it easy to send the dump elsewhere, it can also
be useful as a simple way to disable dumping results.
.SH "CHILD HANDLES"
.IX Header "CHILD HANDLES"
Child handles inherit a reference to the Profile attribute value
of their parent.  So if profiling is enabled for a database handle
then by default the statement handles created from it all contribute
to the same merged profile data tree.
.SH "PROFILE OBJECT METHODS"
.IX Header "PROFILE OBJECT METHODS"
.Sh "format"
.IX Subsection "format"
See \*(L"\s-1REPORTING\s0\*(R".
.Sh "as_node_path_list"
.IX Subsection "as_node_path_list"
.Vb 2
\&  @ary = $dbh\->{Profile}\->as_node_path_list();
\&  @ary = $dbh\->{Profile}\->as_node_path_list($node, $path);
.Ve
.PP
Returns the collected data ($dbh\->{Profile}{Data}) restructured into a list of
array refs, one for each leaf node in the Data tree. This 'flat' structure is
often much simpler for applications to work with.
.PP
The first element of each array ref is a reference to the leaf node.
The remaining elements are the 'path' through the data tree to that node.
.PP
For example, given a data tree like this:
.PP
.Vb 3
\&    {key1a}{key2a}[node1]
\&    {key1a}{key2b}[node2]
\&    {key1b}{key2a}{key3a}[node3]
.Ve
.PP
The \fIas_node_path_list()\fR method  will return this list:
.PP
.Vb 3
\&    [ [node1], \*(Aqkey1a\*(Aq, \*(Aqkey2a\*(Aq ]
\&    [ [node2], \*(Aqkey1a\*(Aq, \*(Aqkey2b\*(Aq ]
\&    [ [node3], \*(Aqkey1b\*(Aq, \*(Aqkey2a\*(Aq, \*(Aqkey3a\*(Aq ]
.Ve
.PP
The nodes are ordered by key, depth-first.
.PP
The \f(CW$node\fR argument can be used to focus on a sub-tree.
If not specified it defaults to \f(CW$dbh\fR\->{Profile}{Data}.
.PP
The \f(CW$path\fR argument can be used to specify a list of path elements that will be
added to each element of the returned list. If not specified it defaults to a a
ref to an empty array.
.Sh "as_text"
.IX Subsection "as_text"
.Vb 8
\&  @txt = $dbh\->{Profile}\->as_text();
\&  $txt = $dbh\->{Profile}\->as_text({
\&      node      => undef,
\&      path      => [],
\&      separator => " > ",
\&      format    => \*(Aq%1$s: %11$fs / %10$d = %2$fs avg (first %12$fs, min %13$fs, max %14$fs)\*(Aq."\en";
\&      sortsub   => sub { ... },
\&  );
.Ve
.PP
Returns the collected data ($dbh\->{Profile}{Data}) reformatted into a list of formatted strings.
In scalar context the list is returned as a single contatenated string.
.PP
A hashref can be used to pass in arguments, the default values are shown in the example above.
.PP
The \f(CW\*(C`node\*(C'\fR and <path> arguments are passed to \fIas_node_path_list()\fR.
.PP
The \f(CW\*(C`separator\*(C'\fR argument is used to join the elemets of the path for each leaf node.
.PP
The \f(CW\*(C`sortsub\*(C'\fR argument is used to pass in a ref to a sub that will order the list.
The subroutine will be passed a reference to the array returned by \fIas_node_path_list()\fR.
.PP
The \f(CW\*(C`format\*(C'\fR argument is a \f(CW\*(C`sprintf\*(C'\fR format string that specifies the format
to use for each leaf node.  It uses the explicit format parameter index
mechanism to specify which of the arguments should appear where in the string.
The arguments to sprintf are:
.PP
.Vb 10
\&     1:  path to node, joined with the separator
\&     2:  average duration (total/count)
\&         (3 thru 9 are currently unused)
\&    10:  count
\&    11:  total duration
\&    12:  first_duration
\&    13:  smallest duration
\&    14:  largest duration
\&    15:  time of first call
\&    16:  time of first call
.Ve
.SH "CUSTOM DATA MANIPULATION"
.IX Header "CUSTOM DATA MANIPULATION"
Recall that \f(CW\*(C`$h\-\*(C'\fR{Profile}\->{Data}> is a reference to the collected data.
Either to a 'leaf' array (when the Path is empty, i.e., \s-1DBI_PROFILE\s0 env var is 1),
or a reference to hash containing values that are either further hash
references or leaf array references.
.PP
Sometimes it's useful to be able to summarise some or all of the collected data.
The \fIdbi_profile_merge_nodes()\fR function can be used to merge leaf node values.
.Sh "dbi_profile_merge_nodes"
.IX Subsection "dbi_profile_merge_nodes"
.Vb 1
\&  use DBI qw(dbi_profile_merge_nodes);
\&
\&  $time_in_dbi = dbi_profile_merge_nodes(my $totals=[], @$leaves);
.Ve
.PP
Merges profile data node. Given a reference to a destination array, and zero or
more references to profile data, merges the profile data into the destination array.
For example:
.PP
.Vb 5
\&  $time_in_dbi = dbi_profile_merge_nodes(
\&      my $totals=[],
\&      [ 10, 0.51, 0.11, 0.01, 0.22, 1023110000, 1023110010 ],
\&      [ 15, 0.42, 0.12, 0.02, 0.23, 1023110005, 1023110009 ],
\&  );
.Ve
.PP
\&\f(CW$totals\fR will then contain
.PP
.Vb 1
\&  [ 25, 0.93, 0.11, 0.01, 0.23, 1023110000, 1023110010 ]
.Ve
.PP
and \f(CW$time_in_dbi\fR will be 0.93;
.PP
The second argument need not be just leaf nodes. If given a reference to a hash
then the hash is recursively searched for for leaf nodes and all those found
are merged.
.PP
For example, to get the time spent 'inside' the \s-1DBI\s0 during an http request,
your logging code run at the end of the request (i.e. mod_perl LogHandler)
could use:
.PP
.Vb 5
\&  my $time_in_dbi = 0;
\&  if (my $Profile = $dbh\->{Profile}) { # if DBI profiling is enabled
\&      $time_in_dbi = dbi_profile_merge_nodes(my $total=[], $Profile\->{Data});
\&      $Profile\->{Data} = {}; # reset the profile data
\&  }
.Ve
.PP
If profiling has been enabled then \f(CW$time_in_dbi\fR will hold the time spent inside
the \s-1DBI\s0 for that handle (and any other handles that share the same profile data)
since the last request.
.PP
Prior to \s-1DBI\s0 1.56 the \fIdbi_profile_merge_nodes()\fR function was called \fIdbi_profile_merge()\fR.
That name still exists as an alias.
.SH "CUSTOM DATA COLLECTION"
.IX Header "CUSTOM DATA COLLECTION"
.Sh "Using The Path Attribute"
.IX Subsection "Using The Path Attribute"
.Vb 6
\&  XXX example to be added later using a selectall_arrayref call
\&  XXX nested inside a fetch loop where the first column of the
\&  XXX outer loop is bound to the profile Path using
\&  XXX bind_column(1, \e${ $dbh\->{Profile}\->{Path}\->[0] })
\&  XXX so you end up with separate profiles for each loop
\&  XXX (patches welcome to add this to the docs :)
.Ve
.Sh "Adding Your Own Samples"
.IX Subsection "Adding Your Own Samples"
The \fIdbi_profile()\fR function can be used to add extra sample data
into the profile data tree. For example:
.PP
.Vb 2
\&    use DBI;
\&    use DBI::Profile (dbi_profile dbi_time);
\&
\&    my $t1 = dbi_time(); # floating point high\-resolution time
\&
\&    ... execute code you want to profile here ...
\&
\&    my $t2 = dbi_time();
\&    dbi_profile($h, $statement, $method, $t1, $t2);
.Ve
.PP
The \f(CW$h\fR parameter is the handle the extra profile sample should be
associated with. The \f(CW$statement\fR parameter is the string to use where
the Path specifies !Statement. If \f(CW$statement\fR is undef
then \f(CW$h\fR\->{Statement} will be used. Similarly \f(CW$method\fR is the string
to use if the Path specifies !MethodName. There is no
default value for \f(CW$method\fR.
.PP
The \f(CW$h\fR\->{Profile}{Path} attribute is processed by \fIdbi_profile()\fR in
the usual way.
.PP
It is recommended that you keep these extra data samples separate
from the \s-1DBI\s0 profile data samples by using values for \f(CW$statement\fR
and \f(CW$method\fR that are distinct from any that are likely to appear
in the profile data normally.
.SH "SUBCLASSING"
.IX Header "SUBCLASSING"
Alternate profile modules must subclass DBI::Profile to help ensure
they work with future versions of the \s-1DBI\s0.
.SH "CAVEATS"
.IX Header "CAVEATS"
Applications which generate many different statement strings
(typically because they don't use placeholders) and profile with
!Statement in the Path (the default) will consume memory
in the Profile Data structure for each statement. Use a code ref
in the Path to return an edited (simplified) form of the statement.
.PP
If a method throws an exception itself (not via RaiseError) then
it won't be counted in the profile.
.PP
If a HandleError subroutine throws an exception (rather than returning
0 and letting RaiseError do it) then the method call won't be counted
in the profile.
.PP
Time spent in \s-1DESTROY\s0 is added to the profile of the parent handle.
.PP
Time spent in \s-1DBI\-\s0>*() methods is not counted. The time spent in
the driver connect method, \f(CW$drh\fR\->\fIconnect()\fR, when it's called by
\&\s-1DBI\-\s0>connect is counted if the \s-1DBI_PROFILE\s0 environment variable is set.
.PP
Time spent fetching tied variables, \f(CW$DBI::errstr\fR, is counted.
.PP
Time spent in \s-1FETCH\s0 for \f(CW$h\fR\->{Profile} is not counted, so getting the profile
data doesn't alter it.
.PP
DBI::PurePerl does not support profiling (though it could in theory).
.PP
A few platforms don't support the \fIgettimeofday()\fR high resolution
time function used by the \s-1DBI\s0 (and available via the \fIdbi_time()\fR function).
In which case you'll get integer resolution time which is mostly useless.
.PP
On Windows platforms the \fIdbi_time()\fR function is limited to millisecond
resolution. Which isn't sufficiently fine for our needs, but still
much better than integer resolution. This limited resolution means
that fast method calls will often register as taking 0 time. And
timings in general will have much more 'jitter' depending on where
within the 'current millisecond' the start and and timing was taken.
.PP
This documentation could be more clear. Probably needs to be reordered
to start with several examples and build from there.  Trying to
explain the concepts first seems painful and to lead to just as
many forward references.  (Patches welcome!)