Provided by: libpoe-perl_1.3670-2_all bug

NAME

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

SYNOPSIS

           sub POE::Kernel::USE_POSIXRT { 0 }
           use POE;

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.

       The monotonic clock is used to keep an ordered queue of events.  The wall clock is used to
       communicate the time with user code ("alarm_set" in POE::Kernel, "alarm_remove" in
       POE::Kernel).

       There are 3 possible clock sources in order of preference: POSIX::RT::Clock, Time::HiRes
       and "time" in perlfunc.  Only "POSIX::RT::Clock" has a separate monotonic and wall clock;
       the other two use the same source for both clocks.

       Clock selection and behaviour is controlled with the following:

   USE_POSIXRT
           export POE_USE_POSIXRT=0
               or
           sub POE::Kernel::USE_POSIXRT { 0 }

       Uses the "monotonic" clock source for queue priority and the "realtime" clock source for
       wall clock.  Not used if POSIX::RT::Clock is not installed or your system does not have a
       "monotonic" clock.

       Defaults to true.  If you want the old POE behaviour, set this to 0.

   USE_STATIC_EPOCH
           export POE_USE_STATIC_EPOCH=0
               or
           sub POE::Kernel::USE_STATIC_EPOCH { 0 }

       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 "alarm" in
       POE::Kernel, "alarm_add" in POE::Kernel and "alarm_set" in POE::Kernel. If
       "USE_STATIC_EPOCH" is true (the default), then the epoch is calculated at load time.  If
       false, the epoch is calculated each time it is needed.

       Defaults to true.  Only relevant for if using POSIX::RT::Clock. Long-running POE servers
       should have this set to false so that system clock skew does mess up the queue.

       It is important to point out that without a static epoch, the ordering of the following
       two alarms is undefined.

           $poe_kernel->alarm_set( a1 => $time );
           $poe_kernel->alarm_set( a2 => $time );

   USE_EXACT_EPOCH
           export POE_USE_EXACT_EPOCH=1
               or
           sub POE::Kernel::USE_EXACT_EPOCH { 1 }

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

       Defaults to false.  Only relevant if "USE_STATIC_EPOCH" is true.

   USE_HIRES
           export POE_USE_HIRES=0
               or
           sub POE::Kernel::USE_HIRES { 0 }

       Use Time::HiRes as both monotonic and wall clock source.  This was POE's previous default
       clock.

       Defaults to true.  Only relevant if "USE_POSIXRT" is false.  Set this to false to use
       "time" in perlfunc.

EXPORTS

       This module optionally exports a few timekeeping helper functions.

   mono2wall
       mono2wall() converts a monotonic time to an epoch wall time.

         my $wall = mono2wall( $monotonic );

   monotime
       monotime() 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.

         my $monotonic = monotime();

   sleep
       sleep() 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.

         sleep( 3.141 );

   time
       time() is a backwards compatible alias for walltime().  Please see walltime()'s
       documentation for details.

   wall2mono
       wall2mono() makes a best-effort attempt to convert wall time to its equivalent monotonic-
       clock time.  Its feature degrades gracefully depending on clock availability.

         my $monotonic = wall2mono( $epoch );

   walltime
       time() makes a best-effort attempt to return non-monotonic wall time at the highest
       available resolution known.

         my $epoch = walltime();

SEE ALSO

       See POE::Resource for general discussion about resources and the classes that manage them.

BUGS

       None known.

AUTHORS & COPYRIGHTS

       Please see POE for more information about authors and contributors.