In Date§

See primary documentation in context for sub sleep-timer

sub sleep-timer(Real() $seconds = Inf --> Duration:D)

This function is implemented like sleep, but unlike the former it does return a Duration instance with the number of seconds the system did not sleep.

In particular, the returned Duration will handle the number of seconds remaining when the process has been awakened by some external event (e.g., Virtual Machine or Operating System events). Under normal condition, when sleep is not interrupted, the returned Duration has a value of 0, meaning no extra seconds remained to sleep. Therefore, in normal situations:

say sleep-timer 3.14;  # OUTPUT: «0␤»

The same result applies to edge cases, when a negative or zero time to sleep is passed as argument:

say sleep-timer -2# OUTPUT: 0 
say sleep-timer 0;  # OUTPUT: 0 

See also sleep-until.