SleepFor functionv0.1.0

pub func SleepFor(span: Duration) -> ! TimeError

At least: the system wakes the thread no earlier, and how much later is the scheduler's business. A negative or zero span returns at once. A signal can interrupt the wait on the Unix systems, and this goes back for the remainder until the whole span has passed — the interruption is invisible, which is what makes this safe to use for pacing. A span longer than one system wait can express is waited for in chunks rather than clamped, so a hundred-day sleep is a hundred days. Fails with InvalidDuration when the system refused the request, which a normalized non-negative span should not produce, and Failed for anything else. A caller with nothing to do about a failed wait says so with SleepFor(span) catch { else => {} }; the point is that it is no longer indistinguishable from success.

Parameters

Returns: nothing when the whole span was waited out, or why it was not

Related

TimeError

pub enum TimeError: uint8 {
    InvalidDuration = 2,
    Failed = 3
}

Why a wait did not happen. Copy. Every case is a failure. An interruption is not one: a waiter that was cut short succeeds with the part of the span still to wait, and SleepFor goes back for it, because a caller that asked for a span asked for the whole span.

Source

Cases

MaximumWaitMilliseconds

pub const MaximumWaitMilliseconds: int64 = 4294967294;

The longest interval one system wait may be asked for, in milliseconds. Windows takes a 32-bit count and reserves 0xFFFFFFFF to mean "wait forever", so the largest finite request is one less. Every system's wait is chunked to this so that the loop is the same everywhere and so that a test of the chunking is a test of what actually runs. About 49.7 days. A span longer than this is waited for in more than one chunk.

Source

WaitChunkMilliseconds

pub func WaitChunkMilliseconds(span: Duration) -> int64

How long the next single wait should be asked for, given how much of the span is left. Returns the whole millisecond count to ask the system for: the remaining span rounded up, since a wait promises at least what was asked and never less, or MaximumWaitMilliseconds when the remainder is longer than one wait can express. Never zero for a positive span, so a loop driven by this always makes progress. A negative or zero span gives zero, which is the value a caller uses to stop. This is where the old clamp was, and it is public so that the hundred-day case can be checked without waiting a hundred days. Cannot fail. Runs in constant time and allocates nothing.

Source

Parameters

Returns: the milliseconds to ask the system for

MaximumWaitAttempts

pub const MaximumWaitAttempts: uint = 4096;

How many waits SleepFor will make before giving up on a span that never shrinks. A Waiter that reports success without waiting and without reducing the remainder would spin forever. This is not a limit any real wait reaches: the system waiter always either advances or fails.

Source

SleepUsing<W>

pub func SleepUsing<W: Waiter>(
    waiter: &var W,
    span: Duration
) -> ! TimeError

Waits out span through waiter, retrying interruptions and chunking what one wait cannot express. A negative or zero span returns at once, having waited for nothing. Otherwise this calls waiter until it reports that nothing is left, so an interruption is invisible to the caller and a span longer than one wait takes several. Fails with whatever the waiter failed with, having stopped there rather than asking again. Fails with Failed when the waiter neither advanced nor failed MaximumWaitAttempts times running, which no real wait does and which is what keeps a broken implementation from hanging a program.

Source

Type parameters

Parameters

Returns: nothing when the whole span was waited out, or why it was not