.\" Automatically generated by Pod::Man 4.11 (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 "POE::Resource::Clock 3pm"
.TH POE::Resource::Clock 3pm "2020-02-07" "perl v5.30.0" "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"
POE::Resource::Clock \- internal clock used for ordering the queue
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    sub POE::Kernel::USE_POSIXRT { 0 }
\&    use POE;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
POE::Resource::Clock is a helper module for POE::Kernel.  It provides the
features to keep an internal monotonic clock and a wall clock.  It also
converts between this monotonic clock and the wall clock.
.PP
The monotonic clock is used to keep an ordered queue of events.  The wall
clock is used to communicate the time with user code
(\*(L"alarm_set\*(R" in POE::Kernel, \*(L"alarm_remove\*(R" in POE::Kernel).
.PP
There are 3 possible clock sources in order of preference:
POSIX::RT::Clock, Time::HiRes and \*(L"time\*(R" in perlfunc.  Only
\&\f(CW\*(C`POSIX::RT::Clock\*(C'\fR has a separate monotonic and wall clock; the other two use the
same source for both clocks.
.PP
Clock selection and behaviour is controlled with the following:
.SS "\s-1USE_POSIXRT\s0"
.IX Subsection "USE_POSIXRT"
.Vb 3
\&    export POE_USE_POSIXRT=0
\&        or
\&    sub POE::Kernel::USE_POSIXRT { 0 }
.Ve
.PP
Uses the \f(CW\*(C`monotonic\*(C'\fR clock source for queue priority and the \f(CW\*(C`realtime\*(C'\fR
clock source for wall clock.  Not used if POSIX::RT::Clock is not installed
or your system does not have a \f(CW\*(C`monotonic\*(C'\fR clock.
.PP
Defaults to true.  If you want the old \s-1POE\s0 behaviour, set this to 0.
.SS "\s-1USE_STATIC_EPOCH\s0"
.IX Subsection "USE_STATIC_EPOCH"
.Vb 3
\&    export POE_USE_STATIC_EPOCH=0
\&        or
\&    sub POE::Kernel::USE_STATIC_EPOCH { 0 }
.Ve
.PP
The epoch of the POSIX::RT::Clock monotonic is different from that of the
realtime clock.  For instance on Linux 2.6.18, the monotonic clock is the
number of seconds since system boot.  This epoch is used to convert from
walltime into monotonic time for \*(L"alarm\*(R" in POE::Kernel,
\&\*(L"alarm_add\*(R" in POE::Kernel and \*(L"alarm_set\*(R" in POE::Kernel. If
\&\f(CW\*(C`USE_STATIC_EPOCH\*(C'\fR is true (the default), then the epoch is calculated at
load time.  If false, the epoch is calculated each time it is needed.
.PP
Defaults to true.  Only relevant for if using POSIX::RT::Clock. Long-running
\&\s-1POE\s0 servers should have this set to false so that system clock skew does
mess up the queue.
.PP
It is important to point out that without a static epoch, the ordering of
the following two alarms is undefined.
.PP
.Vb 2
\&    $poe_kernel\->alarm_set( a1 => $time );
\&    $poe_kernel\->alarm_set( a2 => $time );
.Ve
.SS "\s-1USE_EXACT_EPOCH\s0"
.IX Subsection "USE_EXACT_EPOCH"
.Vb 3
\&    export POE_USE_EXACT_EPOCH=1
\&        or
\&    sub POE::Kernel::USE_EXACT_EPOCH { 1 }
.Ve
.PP
There currently no way to exactly get the monotonic clock's epoch.  Instead
the difference between the current monotonic clock value to the realtime
clock's value is used.  This is obviously inexact because there is a slight
delay between the 2 system calls.  Setting \s-1USE_EXACT_EPOCH\s0 to true will
calculate an average of this difference over 250 ms or at least 20 samples.
What's more, the system calls are done in both orders (monotonic then
realtime, realtime then monotonic) to try and get a more exact value.
.PP
Defaults to false.  Only relevant if \*(L"\s-1USE_STATIC_EPOCH\*(R"\s0 is true.
.SS "\s-1USE_HIRES\s0"
.IX Subsection "USE_HIRES"
.Vb 3
\&    export POE_USE_HIRES=0
\&        or
\&    sub POE::Kernel::USE_HIRES { 0 }
.Ve
.PP
Use Time::HiRes as both monotonic and wall clock source.  This was \s-1POE\s0's
previous default clock.
.PP
Defaults to true.  Only relevant if \*(L"\s-1USE_POSIXRT\*(R"\s0 is false.  Set this to false to use
\&\*(L"time\*(R" in perlfunc.
.SH "EXPORTS"
.IX Header "EXPORTS"
This module optionally exports a few timekeeping helper functions.
.SS "mono2wall"
.IX Subsection "mono2wall"
\&\fBmono2wall()\fR converts a monotonic time to an epoch wall time.
.PP
.Vb 1
\&  my $wall = mono2wall( $monotonic );
.Ve
.SS "monotime"
.IX Subsection "monotime"
\&\fBmonotime()\fR makes a best-effort attempt to return the time from a
monotonic system clock.  It may fall back to non-monotonic time if
there are no monotonic clocks available.
.PP
.Vb 1
\&  my $monotonic = monotime();
.Ve
.SS "sleep"
.IX Subsection "sleep"
\&\fBsleep()\fR makes a best-effort attempt to sleep a particular amount of
high-resolution time using a monotonic clock.  This feature will
degrade gracefully to non-monotonic high-resolution clocks, then
low-resolution clocks, depending on available libraries.
.PP
.Vb 1
\&  sleep( 3.141 );
.Ve
.SS "time"
.IX Subsection "time"
\&\fBtime()\fR is a backwards compatible alias for \fBwalltime()\fR.  Please see
\&\fBwalltime()\fR's documentation for details.
.SS "wall2mono"
.IX Subsection "wall2mono"
\&\fBwall2mono()\fR makes a best-effort attempt to convert wall time to its
equivalent monotonic-clock time.  Its feature degrades gracefully
depending on clock availability.
.PP
.Vb 1
\&  my $monotonic = wall2mono( $epoch );
.Ve
.SS "walltime"
.IX Subsection "walltime"
\&\fBtime()\fR makes a best-effort attempt to return non-monotonic wall time
at the highest available resolution known.
.PP
.Vb 1
\&  my $epoch = walltime();
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See POE::Resource for general discussion about resources and the
classes that manage them.
.SH "BUGS"
.IX Header "BUGS"
None known.
.SH "AUTHORS & COPYRIGHTS"
.IX Header "AUTHORS & COPYRIGHTS"
Please see \s-1POE\s0 for more information about authors and contributors.