Browse files

split sleep() into three functions

Specify sleep in terms of Reals, Durations and Instants, so that Int,
Rat and FatRat types are also allowed as inputs.  Use sleep() now when
you don't care how long it really sleeps, and you may use sleep-timer()
to convey the intent to measure remaining time.  Use sleep-till()
to sleep to a particular Instant without cumulative clock drift.
  • Loading branch information...
1 parent e05910e commit fcd17ad88c4b8002f7ab78a929fe32a6471a70ac @TimToady TimToady committed Sep 4, 2013
Showing with 39 additions and 4 deletions.
  1. +39 −4 S29-functions.pod
View
43 S29-functions.pod
@@ -19,8 +19,8 @@ Synopsis 29: Builtin Functions
Created: 12 Mar 2005
- Last Modified: 1 Sep 2013
- Version: 56
+ Last Modified: 4 Sep 2013
+ Version: 57
The document is a draft.
@@ -255,13 +255,48 @@ an embedded interpreter, all memory must also be reclaimed.
=item sleep
- multi sleep ( Num $for = Inf --> Num )
+ multi sleep ( Real $for = Inf --> Nil )
Attempt to sleep for up to C<$for> seconds. Implementations are obligated
-to support sub-second resolutions if that is at all possible.
+to support sub-second resolutions if that is at all possible. You may pass
+any of C<Int>, C<Num>, C<Rat>, or C<Duration> types as an argument, since those
+all do C<Real>, but regardless of which type you use, they are always scaled to
+seconds. (An implementation is allowed to provide access to a platform-specific
+function based on, say, nanoseconds, but Perl 6 does not presume to know
+how much resolution clocks will have in the future, so requires everything to
+be specified in fractional seconds.)
+
+This function returns nothing; use C<sleep-timer> if you wish it to
+return how much time is remaining on the specified sleep. However,
+if you really just want to keep rolling over in bed until your alarm
+goes off at a particular time, use C<sleep-till> instead, since it
+is not subject to relative clock drift.
See C<Synopsis 17: Concurrency> for more details.
+=item sleep-timer
+
+ multi sleep-timer ( Real $for = Inf --> Duration )
+
+Just like C<sleep>, but returns the amount of time remaining to sleep
+as a C<Duration> (which will be 0 if the call was not interrupted).
+Depending on the platform and the system call involved, this may or
+may not require emulation by interrogating the clock before and after.
+For those systems whose system call returns the remaining time, this
+can be more efficient than interrogating the clock twice yourself,
+However, the optimizer is encouraged to change this to a bare C<sleep>
+in sink context. (But then, you might as well just write that in
+the first place.)
+
+=item sleep-till
+
+ multi sleep-till ( Instant $for = Inf --> Instant )
+
+Just like C<sleep>, but checks the current time and goes back to
+sleep if accidentally woken up early, to guarantee waiting until the
+specified time. Returns the actual current time, since it already
+just looked it up.
+
=item interval
multi interval ( Num $for --> Num )

0 comments on commit fcd17ad

Please sign in to comment.