POE::Resource::Clock(3pm)

1POE::Resource::Clock(3)User Contributed Perl DocumentatioPnOE::Resource::Clock(3)
2
3
4

NAME

6       POE::Resource::Clock - internal clock used for ordering the queue
7

SYNOPSIS

9           sub POE::Kernel::USE_POSIXRT { 0 }
10           use POE;
11

DESCRIPTION

13       POE::Resource::Clock is a helper module for POE::Kernel.  It provides
14       the features to keep an internal monotonic clock and a wall clock.  It
15       also converts between this monotonic clock and the wall clock.
16
17       The monotonic clock is used to keep an ordered queue of events.  The
18       wall clock is used to communicate the time with user code ("alarm_set"
19       in POE::Kernel, "alarm_remove" in POE::Kernel).
20
21       There are 3 possible clock sources in order of preference:
22       POSIX::RT::Clock, Time::HiRes and "time" in perlfunc.  Only
23       "POSIX::RT::Clock" has a separate monotonic and wall clock; the other
24       two use the same source for both clocks.
25
26       Clock selection and behaviour is controlled with the following:
27
28   USE_POSIXRT
29           export POE_USE_POSIXRT=0
30               or
31           sub POE::Kernel::USE_POSIXRT { 0 }
32
33       Uses the "monotonic" clock source for queue priority and the "realtime"
34       clock source for wall clock.  Not used if POSIX::RT::Clock is not
35       installed or your system does not have a "monotonic" clock.
36
37       Defaults to true.  If you want the old POE behaviour, set this to 0.
38
39   USE_STATIC_EPOCH
40           export POE_USE_STATIC_EPOCH=0
41               or
42           sub POE::Kernel::USE_STATIC_EPOCH { 0 }
43
44       The epoch of the POSIX::RT::Clock monotonic is different from that of
45       the realtime clock.  For instance on Linux 2.6.18, the monotonic clock
46       is the number of seconds since system boot.  This epoch is used to
47       convert from walltime into monotonic time for "alarm" in POE::Kernel,
48       "alarm_add" in POE::Kernel and "alarm_set" in POE::Kernel. If
49       "USE_STATIC_EPOCH" is true (the default), then the epoch is calculated
50       at load time.  If false, the epoch is calculated each time it is
51       needed.
52
53       Defaults to true.  Only relevant for if using POSIX::RT::Clock. Long-
54       running POE servers should have this set to false so that system clock
55       skew does mess up the queue.
56
57       It is important to point out that without a static epoch, the ordering
58       of the following two alarms is undefined.
59
60           $poe_kernel->alarm_set( a1 => $time );
61           $poe_kernel->alarm_set( a2 => $time );
62
63   USE_EXACT_EPOCH
64           export POE_USE_EXACT_EPOCH=1
65               or
66           sub POE::Kernel::USE_EXACT_EPOCH { 1 }
67
68       There currently no way to exactly get the monotonic clock's epoch.
69       Instead the difference between the current monotonic clock value to the
70       realtime clock's value is used.  This is obviously inexact because
71       there is a slight delay between the 2 system calls.  Setting
72       USE_EXACT_EPOCH to true will calculate an average of this difference
73       over 250 ms or at least 20 samples.  What's more, the system calls are
74       done in both orders (monotonic then realtime, realtime then monotonic)
75       to try and get a more exact value.
76
77       Defaults to false.  Only relevant if "USE_STATIC_EPOCH" is true.
78
79   USE_HIRES
80           export POE_USE_HIRES=0
81               or
82           sub POE::Kernel::USE_HIRES { 0 }
83
84       Use Time::HiRes as both monotonic and wall clock source.  This was
85       POE's previous default clock.
86
87       Defaults to true.  Only relevant if "USE_POSIXRT" is false.  Set this
88       to false to use "time" in perlfunc.
89

EXPORTS

91       This module optionally exports a few timekeeping helper functions.
92
93   mono2wall
94       mono2wall() converts a monotonic time to an epoch wall time.
95
96         my $wall = mono2wall( $monotonic );
97
98   monotime
99       monotime() makes a best-effort attempt to return the time from a
100       monotonic system clock.  It may fall back to non-monotonic time if
101       there are no monotonic clocks available.
102
103         my $monotonic = monotime();
104
105   sleep
106       sleep() makes a best-effort attempt to sleep a particular amount of
107       high-resolution time using a monotonic clock.  This feature will
108       degrade gracefully to non-monotonic high-resolution clocks, then low-
109       resolution clocks, depending on available libraries.
110
111         sleep( 3.141 );
112
113   time
114       time() is a backwards compatible alias for walltime().  Please see
115       walltime()'s documentation for details.
116
117   wall2mono
118       wall2mono() makes a best-effort attempt to convert wall time to its
119       equivalent monotonic-clock time.  Its feature degrades gracefully
120       depending on clock availability.
121
122         my $monotonic = wall2mono( $epoch );
123
124   walltime
125       time() makes a best-effort attempt to return non-monotonic wall time at
126       the highest available resolution known.
127
128         my $epoch = walltime();
129

BUGS

135       None known.
136

AUTHORS & COPYRIGHTS

138       Please see POE for more information about authors and contributors.
139
140
141
142perl v5.30.1                      2020-02-05           POE::Resource::Clock(3)

NAME

SYNOPSIS

DESCRIPTION

EXPORTS

SEE ALSO

BUGS

AUTHORS & COPYRIGHTS