NAME

DashProfiler::Sample - encapsulates the acquisition of a single sample

DESCRIPTION

Firstly, read DashProfiler::UserGuide for a general introduction.

A DashProfiler::Sample object is returned from the prepare() method of DashProfiler::Core, or from the functions imported by DashProfiler::Import.

The object, and this class, are rarely used directly.

METHODS

new

This method is normally only called by the code reference returned from the DashProfiler::Core prepare() method, and not directly.

    $sample = DashProfiler::Sample->new($meta, $context2);
    $sample = DashProfiler::Sample->new($meta, $context2, $start_time, $allow_overlap);

The returned object encapsulates the time of its creation and the supplied arguments.

The $meta parameter must be a hash reference containing at least a '_dash_profile' element which must be a reference to a DashProfiler::Core object. The new() method marks the profile as 'in use'.

If the $context2 is false then $meta->{_context2} is used instead.

If $start_time false, which it normally is, then the value returned by dbi_time() is used instead.

If $allow_overlap is false, which it normally is, then if the DashProfiler refered to by the '_dash_profile' element of %$meta is marked as 'in use' then a warning is given (just once) and new returns undef, so no sample is taken.

If $allow_overlap is true, then overlaping samples can be taken. However, if samples do overlap then period_exclusive is disabled for that DashProfiler.

current_sample_duration

  $ps = foo_profiler(...);
  my $duration = $ps->current_sample_duration();

Returns the amount of time since the sample was created.

DESTROY

When the DashProiler::Sample object is destroyed it:

 - calls dbi_time() to get the time of the end of the sample

 - marks the profile as no longer 'in use'

 - adds the timespan of the sample to the 'period_accumulated' of the DashProiler

 - extracts context2 from the DashProiler::Sample object. If it's a code reference
   then it's executed and the return value is used as context2.
   This is very useful where the value of context2 can't be determined
   at the time the sample is started.

 - if the $meta hash reference (passed to new()) contained a 'C<context2edit>'
   code reference then it's called and passed context2 and $meta.
   The return value is used as context2.

 - calls DBI::Profile::dbi_profile(handle, context1, context2, start time, end time)
   for each DBI profile currently attached to the DashProiler.

DEBUG

The DEBUG subroutine is a constant that returns whatever the value of

    $ENV{DASHPROFILER_SAMPLE_DEBUG} || $ENV{DASHPROFILER_DEBUG} || 0;

was when the modle was loaded.

AUTHOR

DashProfiler by Tim Bunce, http://www.tim.bunce.name and http://blog.timbunce.org

COPYRIGHT

The DashProfiler distribution is Copyright (c) 2007-2008 Tim Bunce. Ireland. All rights reserved.

You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.