POE::R...:Clock(3pm)

💖 POE::Resource::Clock — the internal clock that keeps your queue in line 💖

So bestie, you found POE::Resource::Clock(3pm) in the User Contributed Perl Documentation section, and honestly? It's giving backstage-pass energy. Come on in. 🎀

---

✨ NAME ✨

POE::Resource::Clock — the internal clock used for ordering the queue 🕰️

---

🌸 SYNOPSIS 🌸

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

---

🦋 DESCRIPTION 🦋

Okay so here's the tea. POE::Resource::Clock is a helper module for POE::Kernel. It brings the features that keep an internal monotonic clock and a wall clock, and it also converts between those two. Iconic multi-tasking behaviour, no notes. 💅

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

There are 3 possible clock sources in order of preference: POSIX::RT::Clock, Time::HiRes and "time" in perlfunc. And here's the important part — only POSIX::RT::Clock has a separate monotonic and wall clock; the other two use the same source for both clocks. So like, one clock doing double duty. Respect.

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. It just straight up isn't used if POSIX::RT::Clock is not installed, or if 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.

🚨 Bestie, listen. 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 );

Like, undefined undefined. Don't come for the module when the order is chaos. 💀

⚙️ 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. (Yeah, we know. 😭) 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. Look at her doing the extra credit work. 📚✨

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 — a true throwback, vintage era. 🎀

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. Little gifts, just for you. 🫶

💜 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. It's doing its best, okay?? 😤

  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. Graceful degradation is such main character energy. 🧚

  sleep( 3.141 );

💜 time

time() is a backwards compatible alias for walltime(). Please see walltime()'s documentation for details. (Yes, scroll down. It's right there. 👇)

💜 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. (The docs really said time() here, and we are not fixing it. Preserve the lore. 📜)

  my $epoch = walltime();

---

🌈 SEE ALSO 🌈

See POE::Resource for general discussion about resources and the classes that manage them. Go read it, it's the prequel. 🍓

---

💀 BUGS 💀

None known. A flawless queen. No cap.

---

🌸 AUTHORS & COPYRIGHTS 🌸

Please see POE for more information about authors and contributors. Credit where credit is due, always. 💖

---

And that's the whole page, bestie — this was perl v5.34.0, dated 2022-03-25, signing off. Stay monotonic, keep your queue ordered, and don't let the system clock skew catch you slipping. ✨💅🦋