view release on metacpan or  search on metacpan

lib/Devel/StatProfiler.pm  view on Meta::CPAN

No source code is saved in the profile file.

=item traced_evals

Only the source code for eval()s that have at least one sample
B<during evaluation> is saved.  This does B<NOT> include eval()s that
define subroutines that are sampled after the eval() ends.

=item all_evals

The source code for all eval()s is saved in the profile file.

=item all_evals_always

The source code for all eval()s is saved in the profile file, even
when profiling is disabled.

=back

=head3 -depth <stack depth> (default 20)

Sets the maximum number of stack frames saved for each sample.

=head3 -metadata HASHREF

Emit custom metadata in the header section of each profile file; this
metadata will be available right after calling C<<
Devel::StatProfiler::Reader->new >>.

=head3 -file <path>

In general, using C<-template> above is the preferred option, since
C<-file> will not work when using C<fork()> or threads.

Sets the exact file path used for profile output file; if the file is
already present, it's overwritten.

=head1 CAVEATS

=head2 goto &subroutine

With a sampling profiler there is no reliable way to track the C<goto
&foo> construct, hence the profile data for this code

    sub foo {
        # 100 milliseconds of computation
    }

    sub bar {
        # 100 milliseconds of computation, then
        goto &foo;
    }

    bar() for 1..100000; # foo.pl, line 10

will report that the code at F<foo.pl> line 10 has spent approximately
the same time in calling C<foo> and C<bar>, and will report C<foo> as
being called from the main program rather than from C<bar>.

=head2 XSUBs with callbacks

Since XSUBs don't have a Perl-level stack frame, Perl code called from
XSUBs is reported as if called from the source line calling the XSUB.

Additionally, the exclusive time for the XSUB incorrectly includes the
time spent in callbacks.

=head2 XSUBs and overload

If an object has an overloaded C<&{}> operator (code dereference)
returning an XSUB as the code reference, the overload might be called
twice in some situations.

=head2 changing profiler state

Calling C<enable_profile>, C<disable_profile> and
C<stop_profile> from an inner runloop (including but not limited to
from C<use>, C<require>, C<sort> blocks, callbacks invoked from XS
code) can have confusing results: runloops started afterwards will
honor the new state, outer runloops will not.

Unfortunately there is no way to detect the situaltion at the moment.

=head2 source code and C<#line> directives

The parsing of C<#line> directive used to map logical lines to
physical lines uses heuristics, and they can obviously fail.

Files that contain C<#line> directives and have no samples taken in
the part of the file outside the part mapped by C<#line> directives
will not be found.

=head2 first line of subs

The first line of subs is found by searching for the sub definition in
the code. Needless to say, this is fragile.

=head2 sampling accuracy

Since the profiler uses C<nanosleep>/C<Sleep> between samples,
accuracy is at the mercy of the OS scheduler.  In particular, under
Windows the default system timer has an accuracy of about 15.6
milliseconds.

=head1 AUTHORS

=over 4

=item *

Mattia Barbon <mattia@barbon.org>

=item *

Steffen Mueller <smueller@cpan.org>

=back

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Mattia Barbon, Steffen Mueller.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut