sane-sleep.md

I'd like to change the NQP op set to provide two distinct sleep ops taking integer arguments in micro-second (or milli-second?) precision:

trysleep    r(int64)
sleep       w(int64) r(int64)

User-facing would be the following subs defined in the setting:

sub microsleep($micros) {
    nqp::trysleep($micros);
}

sub sleep($secs) {
    nqp::sleep(nqp::ceil_n($secs * 1e6)) / 1e6;
}

Use microsleep() if you don't care for the exact amount of time actually passed (in particular if you want to return early in case of thread interruption).

Use sleep() if you want to have a guarantee that we slept for at least the specified amount of time (even in case of thread interruption) and if the actual wallclock time is relevant, eg when doing simulations that need predictable ticks.

On MoarVM, these would be backed by

/* Tries to sleep for the requested number of nanoseconds. */
void MVM_platform_nanosleep(MVMuint64 nanos);

/* Same as MVM_platform_nanosleep(), but retries on premature
 * interruption and returns the time actually slept.
 *
 * A return value less than the requested time indicates an
 * error and should only happen rarely, if at all.
 */
MVMuint64 MVM_platform_nanosleep_retry(MVMuint64 nanos);

We use nanoseconds here because that's the POSIX API functions we use by default and for consistency with MVM_platform_now(). This of course doesn't say anything about actual precision.