First draft of Telemetry::Period documentation

Telemetry::Period.pod6

=begin pod

=TITLE class Telemetry::Period

=SUBTITLE Performance data over a period

    class Telemetry::Period { }

A C<Telemetry::Period> object contains the difference between two C<Telemetry>
objects.  It is generally not created by calling .new, but it can be if needed:
it takes "cpu-user", "cpu-sys" and "wallclock" as named parameters.

=begin code
# basic usage
use Telemetry;
my $t0 = Telemetry.new;
# execute some code
my $t1 = Telemetry.new;
my $period = $t1 - $t0;  # creates Telemetry::Period object
say "Code took $period (cpu / wallclock) microseconds to execute";
=end

=head1 Methods

=head2 method cpu

Returns the total amount of CPU time of this period (in microseconds),
essentially the sum of C<cpu-user> and C<cpu-sys>.

=head2 method cpu-user

Returns the amount of CPU time spent on executing user code of this period
(in microseconds).

=head2 method cpu-sys

Returns the amount of CPU time spent in system overhead of this period (in
microseconds).
  
=head2 method wallclock

Returns the length of the period (in microseconds).

=head2 method gist / method Str

Returns a string representation in the form "cpu / wallclock".

=head2 method cpus

Returns the number of CPUs that were in full use on average in this period
(basically cpu divided by wallclock).

=head2 method utilization

Returns the % of CPUs that were used in average in this period.

=head1 See Also

L<Telemetry>

=end pod