.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Catalyst::Stats 3pm"
.TH Catalyst::Stats 3pm "2019-01-19" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Catalyst::Stats \- Catalyst Timing Statistics Class
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 7
\&    $stats = $c\->stats;
\&    $stats\->enable(1);
\&    $stats\->profile($comment);
\&    $stats\->profile(begin => $block_name, comment =>$comment);
\&    $stats\->profile(end => $block_name);
\&    $elapsed = $stats\->elapsed;
\&    $report = $stats\->report;
.Ve
.PP
See Catalyst.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides the default, simple timing stats collection functionality for Catalyst.
If you want something different set \f(CW\*(C`MyApp\->stats_class\*(C'\fR in your application module,
e.g.:
.PP
.Vb 1
\&    _\|_PACKAGE_\|_\->stats_class( "My::Stats" );
.Ve
.PP
If you write your own, your stats object is expected to provide the interface described here.
.PP
Catalyst uses this class to report timings of component actions.  You can add
profiling points into your own code to get deeper insight. Typical usage might
be like this:
.PP
.Vb 10
\&  sub mysub {
\&    my ($c, ...) = @_;
\&    $c\->stats\->profile(begin => "mysub");
\&    # code goes here
\&    ...
\&    $c\->stats\->profile("starting critical bit");
\&    # code here too
\&    ...
\&    $c\->stats\->profile("completed first part of critical bit");
\&    # more code
\&    ...
\&    $c\->stats\->profile("completed second part of critical bit");
\&    # more code
\&    ...
\&    $c\->stats\->profile(end => "mysub");
\&  }
.Ve
.PP
Supposing mysub was called from the action \*(L"process\*(R" inside a Catalyst
Controller called \*(L"service\*(R", then the reported timings for the above example
might look something like this:
.PP
.Vb 10
\&  .\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-.
\&  | Action                                                         | Time      |
\&  +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-+
\&  | /service/process                                               | 1.327702s |
\&  |  mysub                                                         | 0.555555s |
\&  |   \- starting critical bit                                      | 0.111111s |
\&  |   \- completed first part of critical bit                       | 0.333333s |
\&  |   \- completed second part of critical bit                      | 0.111000s |
\&  | /end                                                           | 0.000160s |
\&  \*(Aq\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\*(Aq
.Ve
.PP
which means mysub took 0.555555s overall, it took 0.111111s to reach the
critical bit, the first part of the critical bit took 0.333333s, and the second
part 0.111s.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
Constructor.
.PP
.Vb 1
\&    $stats = Catalyst::Stats\->new;
.Ve
.SS "enable"
.IX Subsection "enable"
.Vb 2
\&    $stats\->enable(0);
\&    $stats\->enable(1);
.Ve
.PP
Enable or disable stats collection.  By default, stats are enabled after object creation.
.SS "profile"
.IX Subsection "profile"
.Vb 3
\&    $stats\->profile($comment);
\&    $stats\->profile(begin => $block_name, comment =>$comment);
\&    $stats\->profile(end => $block_name);
.Ve
.PP
Marks a profiling point.  These can appear in pairs, to time the block of code
between the begin/end pairs, or by themselves, in which case the time of
execution to the previous profiling point will be reported.
.PP
The argument may be either a single comment string or a list of name-value
pairs.  Thus the following are equivalent:
.PP
.Vb 2
\&    $stats\->profile($comment);
\&    $stats\->profile(comment => $comment);
.Ve
.PP
The following key names/values may be used:
.IP "\(bu" 4
begin => \s-1ACTION\s0
.Sp
Marks the beginning of a block.  The value is used in the description in the
timing report.
.IP "\(bu" 4
end => \s-1ACTION\s0
.Sp
Marks the end of the block.  The name given must match a previous 'begin'.
Correct nesting is recommended, although this module is tolerant of blocks that
are not correctly nested, and the reported timings should accurately reflect the
time taken to execute the block whether properly nested or not.
.IP "\(bu" 4
comment => \s-1COMMENT\s0
.Sp
Comment string; use this to describe the profiling point.  It is combined with
the block action (if any) in the timing report description field.
.IP "\(bu" 4
uid => \s-1UID\s0
.Sp
Assign a predefined unique \s-1ID.\s0  This is useful if, for whatever reason, you wish
to relate a profiling point to a different parent than in the natural execution
sequence.
.IP "\(bu" 4
parent => \s-1UID\s0
.Sp
Explicitly relate the profiling point back to the parent with the specified \s-1UID.\s0
The profiling point will be ignored if the \s-1UID\s0 has not been previously defined.
.PP
Returns the \s-1UID\s0 of the current point in the profile tree.  The \s-1UID\s0 is
automatically assigned if not explicitly given.
.SS "created"
.IX Subsection "created"
.Vb 1
\&    ($seconds, $microseconds) = $stats\->created;
.Ve
.PP
Returns the time the object was created, in \f(CW\*(C`gettimeofday\*(C'\fR format, with
Unix epoch seconds followed by microseconds.
.SS "elapsed"
.IX Subsection "elapsed"
.Vb 1
\&    $elapsed = $stats\->elapsed
.Ve
.PP
Get the total elapsed time (in seconds) since the object was created.
.SS "report"
.IX Subsection "report"
.Vb 3
\&    print $stats\->report ."\en";
\&    $report = $stats\->report;
\&    @report = $stats\->report;
.Ve
.PP
In scalar context, generates a textual report.  In array context, returns the
array of results where each row comprises:
.PP
.Vb 1
\&    [ depth, description, time, rollup ]
.Ve
.PP
The depth is the calling stack level of the profiling point.
.PP
The description is a combination of the block name and comment.
.PP
The time reported for each block is the total execution time for the block, and
the time associated with each intermediate profiling point is the elapsed time
from the previous profiling point.
.PP
The 'rollup' flag indicates whether the reported time is the rolled up time for
the block, or the elapsed time from the previous profiling point.
.SH "COMPATIBILITY METHODS"
.IX Header "COMPATIBILITY METHODS"
Some components might expect the stats object to be a regular Tree::Simple object.
We've added some compatibility methods to handle this scenario:
.SS "accept"
.IX Subsection "accept"
.SS "addChild"
.IX Subsection "addChild"
.SS "setNodeValue"
.IX Subsection "setNodeValue"
.SS "getNodeValue"
.IX Subsection "getNodeValue"
.SS "traverse"
.IX Subsection "traverse"
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Catalyst
.SH "AUTHORS"
.IX Header "AUTHORS"
Catalyst Contributors, see Catalyst.pm
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This library is free software. You can redistribute it and/or modify
it under the same terms as Perl itself.