run-fibers returns when initial fiber finishes

* epoll.c (scm_primitive_epoll_wait): Accept timeout in internal time
  units instead of milliseconds.  Avoid some overhead if the timeout is
  zero.
* fibers/epoll.scm (epoll): Adapt to primitive-epoll-wait chance.
  Change get-timeout callback to an "expiry" argument and an
  update-expiry last-minute function.  Tighten the window around the
  "waiting" epoll-state.
* fibers.scm (%run-fibers): Remove current-read-waiter /
  current-write-waiter parameterization, given that fibers individually
  each have this parameterization.
  (run-fibers): Add #:drain? argument.
* fibers/internal.scm (schedule-runnables-for-next-turn): Simplify a
  bit, inlining scheduler-poll-timeout and adapting to epoll change.
  (scheduler-work-pending?): New function.
  (run-scheduler): Simplify finish? logic.
* tests/basic.scm:
* tests/speedup.scm: Update to drain where needed.
* fibers.texi: Update for new run-fibers termination condition.

1 files changed, 7 insertions, 8 deletions

diff --git a/fibers.texi b/fibers.texi
index 27e7079..1549136 100644
--- a/fibers.texi
+++ b/fibers.texi
@@ -372,11 +372,6 @@ fully cooperative scheduling model.
 To enable expressive cross-kernel-thread communications, channel sends
 and receives are atomic and thread-safe.
 
-To start scheduling fibers, user code will typically create a
-scheduler, instate it on the thread, add some fibers, then run the
-scheduler.  That call to run the scheduler will only return when there
-there are no more fibers waiting to be scheduled.
-
 @node Parallelism
 @section Parallelism
 
@@ -480,10 +475,10 @@ thread, use @code{run-fibers}.
        [#:scheduler=@code{#f}] @
        [#:parallelism=@code{(current-processor-count)}] @
        [#:cpus=@code{(getaffinity 0)}] @
-       [#:hz=100]
+       [#:hz=@code{100}] [#:drain?=@code{#f}]
 Run @var{init-thunk} within a fiber in a fresh scheduler, blocking
-until the scheduler has no more runnable fibers.  Return the value(s)
-returned by the call to @var{init-thunk}.
+until @var{init-thunk} returns.  Return the value(s) returned by the
+call to @var{init-thunk}.
 
 For example:
 @example
@@ -510,6 +505,10 @@ create one), you can pass it to @code{run-fibers} using the
 @code{#:scheduler} keyword argument.  In that case the scheduler will
 not be destroyed when @code{run-fibers} finishes.
 
+@code{run-fibers} will return when the @var{init-thunk} call returns.
+To make it additionally wait until there are no more runnable fibers
+or pending timeouts, specify the @code{#:drain? #t} keyword argument.
+
 If @code{run-fibers} creates a scheduler on your behalf, it will
 arrange for a number of ``peer'' schedulers to also be created, up to
 a total scheduler count controlled by the @var{parallelism} keyword