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.

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 $meta (passed to new()) contained a 'C<context2edit>' code reference
  then it's called and passed context2 and $meta. The return value is used
  and context2. This is very useful where the value of context2 can't be determined
  at the time the sample is started.

- 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.