summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAndy Wingo <wingo@pobox.com>2016-10-12 13:12:07 +0200
committerAndy Wingo <wingo@pobox.com>2016-10-12 13:12:07 +0200
commit5ce060dcc898cd186b35bd3bef57f2dc3bf71a41 (patch)
tree3051c84758a867d4699c14c867dc1f9209ddf81a
parentEpoll handles event buffer size itself (diff)
downloadguile-fibers-5ce060dcc898cd186b35bd3bef57f2dc3bf71a41.tar.gz
Update documentation.
-rw-r--r--TODO.md22
-rw-r--r--fibers/channels.scm46
-rw-r--r--fibers/internal.scm39
-rw-r--r--fibers/operations.scm9
-rw-r--r--fibers/timers.scm6
5 files changed, 85 insertions, 37 deletions
diff --git a/TODO.md b/TODO.md
index f1e5c82..1e4153c 100644
--- a/TODO.md
+++ b/TODO.md
@@ -37,7 +37,7 @@ very performant.
scheme@(guile-user)> ,fkill 1
```
-Also `,fcancel` I guess, the difference being that killing raises and
+Also `,fcancel` I guess, the difference being that killing raises an
exception and cancelling is like SIGKILL.
### `,fiber N`
@@ -57,17 +57,11 @@ to get the dynamic bindings too, methinks...
Currently fibers have no priority. Does that matter?
-## Fiber join
+## Fiber join?
-First, spawn-fiber needs to return the new fiber, and we need to test
-that current-fiber works. Then join-fiber on a not-finished fiber
-should suspend the calling fiber, waking it up when the callee
-finishes.
-
-Do fibers each need a field for other fibers that want to join on
-them? Are there other ways? I suspect most fibers will not be joined
-and just GC'd when finished or stuck, so maybe a side table is the
-right solution.
+Currently there is no ability to join a fiber. I don't know if this
+matters or not though. Certainly you can build this facility by
+wrapping the fiber's continuation when you create it.
## Process death notifications
@@ -115,12 +109,6 @@ We need to provide API for things like:
Also, how would we do it?
-## Prevent scheduler from being active in multiple threads at once
-
-A scheduler assumes that it can directly mutate some of its data
-structures, meaning that it should never run on multiple threads at
-once.
-
## `select()` or similar
We should certainly provide a `select-message` interface that returns
diff --git a/fibers/channels.scm b/fibers/channels.scm
index c37cac9..c38ac31 100644
--- a/fibers/channels.scm
+++ b/fibers/channels.scm
@@ -35,6 +35,7 @@
#:use-module (fibers internal)
#:use-module (fibers operations)
#:export (make-channel
+ channel?
put-operation
get-operation
put-message
@@ -49,10 +50,13 @@
(putq channel-putq))
(define (make-channel)
+ "Make a fresh channel."
(%make-channel (make-atomic-box (make-empty-deque))
(make-atomic-box (make-empty-deque))))
-(define (put-operation channel msg)
+(define (put-operation channel message)
+ "Make an operation that if and when it completes will rendezvous
+with a receiver fiber to send @var{message} over @var{channel}."
(match channel
(($ <channel> getq-box putq-box)
(define (try-fn)
@@ -83,8 +87,8 @@
(maybe-commit)
(resume-fiber get-fiber (if get-wrap-fn
(lambda ()
- (get-wrap-fn msg))
- (lambda () msg)))
+ (get-wrap-fn message))
+ (lambda () message)))
;; Continue directly.
(lambda () (values)))
;; Get operation temporarily busy; try again.
@@ -104,7 +108,7 @@
(#(get-flag get-fiber get-wrap-fn)
(not (eq? put-flag get-flag)))))
;; First, publish this put operation.
- (enqueue! putq-box (vector put-flag put-fiber put-wrap-fn msg))
+ (enqueue! putq-box (vector put-flag put-fiber put-wrap-fn message))
;; In the try phase, we scanned the getq for a get operation,
;; but we were unable to perform any of them. Since then,
;; there might be a new get operation on the queue. However
@@ -149,8 +153,8 @@
(maybe-commit)
(resume-fiber get-fiber
(if get-wrap-fn
- (lambda () (get-wrap-fn msg))
- (lambda () msg)))
+ (lambda () (get-wrap-fn message))
+ (lambda () message)))
(resume-fiber put-fiber (or put-wrap-fn values))
(values))
('C
@@ -174,6 +178,8 @@
(make-base-operation #f try-fn block-fn))))
(define (get-operation channel)
+ "Make an operation that if and when it completes will rendezvous
+with a sender fiber to receive one value from @var{channel}."
(match channel
(($ <channel> getq-box putq-box)
(define (try-fn)
@@ -190,7 +196,7 @@
;; Return #f if the putq was empty.
(and putq*
(match item
- (#(put-flag put-fiber put-wrap-fn msg)
+ (#(put-flag put-fiber put-wrap-fn message)
(let spin ()
(match (atomic-box-compare-and-swap! put-flag 'W 'S)
('W
@@ -202,7 +208,7 @@
(maybe-commit)
(resume-fiber put-fiber (or put-wrap-fn values))
;; Continue directly.
- (lambda () msg))
+ (lambda () message))
;; Put operation temporarily busy; try again.
('C (spin))
;; Put operation already synchronized; pop it
@@ -217,7 +223,7 @@
;; channel's getq.
(define (not-me? item)
(match item
- (#(put-flag put-fiber put-wrap-fn msg)
+ (#(put-flag put-fiber put-wrap-fn message)
(not (eq? get-flag put-flag)))))
;; First, publish this get operation.
(enqueue! getq-box (vector get-flag get-fiber get-wrap-fn))
@@ -243,7 +249,7 @@
;; We only have to service the putq if it is non-empty.
(when putq*
(match item
- (#(put-flag put-fiber put-wrap-fn msg)
+ (#(put-flag put-fiber put-wrap-fn message)
(match (atomic-box-ref put-flag)
('S
;; This put operation has already synchronized;
@@ -266,8 +272,8 @@
(maybe-commit)
(resume-fiber get-fiber
(if get-wrap-fn
- (lambda () (get-wrap-fn msg))
- (lambda () msg)))
+ (lambda () (get-wrap-fn message))
+ (lambda () message)))
(resume-fiber put-fiber (or put-wrap-fn values))
(values))
('C
@@ -290,8 +296,16 @@
(values)))))))))))))
(make-base-operation #f try-fn block-fn))))
-(define (put-message ch exp)
- (perform-operation (put-operation ch exp)))
+(define (put-message channel message)
+ "Send @var{message} on @var{channel}, and return zero values. If
+there is already another fiber waiting to receive a message on this
+channel, give it our message and continue. Otherwise, block until a
+receiver becomes available."
+ (perform-operation (put-operation channel message)))
-(define (get-message ch)
- (perform-operation (get-operation ch)))
+(define (get-message channel)
+ "Receive a message from @var{channel} and return it. If there is
+already another fiber waiting to send a message on this channel, take
+its message directly. Otherwise, block until a sender becomes
+available."
+ (perform-operation (get-operation channel)))
diff --git a/fibers/internal.scm b/fibers/internal.scm
index 8b603b4..bd7ba64 100644
--- a/fibers/internal.scm
+++ b/fibers/internal.scm
@@ -55,13 +55,21 @@
(define-once schedulers-nameset (make-nameset))
(define (fold-all-schedulers f seed)
+ "Fold @var{f} over the set of known schedulers. @var{f} will be
+invoked as @code{(@var{f} @var{name} @var{scheduler} @var{seed})}."
(nameset-fold f schedulers-nameset seed))
(define (scheduler-by-name name)
+ "Return the scheduler named @var{name}, or @code{#f} if no scheduler
+of that name is known."
(nameset-ref schedulers-nameset name))
(define (fold-all-fibers f seed)
+ "Fold @var{f} over the set of known fibers. @var{f} will be
+invoked as @code{(@var{f} @var{name} @var{fiber} @var{seed})}."
(nameset-fold f fibers-nameset seed))
(define (fiber-by-name name)
+ "Return the fiber named @var{name}, or @code{#f} if no fiber of that
+name is known."
(nameset-ref fibers-nameset name))
(define-record-type <scheduler>
@@ -103,6 +111,7 @@
(error "owned by other thread" prev))))))))
(define (make-scheduler)
+ "Make a new scheduler in which to run fibers."
(let ((epfd (epoll-create))
(active-fd-count 0)
(prompt-tag (make-prompt-tag "fibers"))
@@ -118,6 +127,10 @@
sched)))
(define-syntax-rule (with-scheduler scheduler body ...)
+ "Evaluate @code{(begin @var{body} ...)} in an environment in which
+@var{scheduler} is bound to the current kernel thread and marked as
+current. Signal an error if @var{scheduler} is already running in
+some other kernel thread."
(let ((sched scheduler))
(dynamic-wind (lambda ()
((scheduler-kernel-thread sched) (current-thread)))
@@ -128,6 +141,8 @@
((scheduler-kernel-thread sched) #f)))))
(define (scheduler-kernel-thread/public sched)
+ "Return the kernel thread on which @var{sched} is running, or
+@code{#f} if @var{sched} is not running."
((scheduler-kernel-thread sched)))
(define current-scheduler (make-parameter #f))
@@ -242,6 +257,9 @@
(after-suspend fiber)))))
(define* (run-scheduler sched)
+ "Run @var{sched} until there are no more fibers ready to run, no
+file descriptors being waited on, and no more timers pending to run.
+Return zero values."
(let lp ()
(schedule-runnables-for-next-turn sched)
(match (dequeue-all! (scheduler-runqueue sched))
@@ -258,18 +276,23 @@
(lp)))))
(define (destroy-scheduler sched)
+ "Release any resources associated with @var{sched}."
#;
(for-each kill-fiber (list-copy (scheduler-fibers sched)))
(epoll-destroy (scheduler-epfd sched)))
(define (create-fiber sched thunk)
+ "Spawn a new fiber in @var{sched} with the continuation @var{thunk}.
+The fiber will be scheduled on the next turn."
(let ((fiber (make-fiber sched #f)))
(nameset-add! fibers-nameset fiber)
(schedule-fiber! fiber thunk)
fiber))
(define (kill-fiber fiber)
- (pk 'kill-fiber fiber))
+ "Try to kill @var{fiber}, causing it to raise an exception. Note
+that this is currently unimplemented!"
+ (error "kill-fiber is unimplemented"))
;; The AFTER-SUSPEND thunk allows the user to suspend the current
;; fiber, saving its state, and then perform some other nonlocal
@@ -277,13 +300,19 @@
;;
(define* (suspend-current-fiber #:optional
(after-suspend (lambda (fiber) #f)))
+ "Suspend the current fiber. Call the optional @var{after-suspend}
+callback, if present, with the suspended thread as its argument."
((abort-to-prompt (scheduler-prompt-tag (current-scheduler))
after-suspend)))
(define* (resume-fiber fiber thunk)
- (let* ((cont (fiber-continuation fiber))
- (thunk (if cont (lambda () (cont thunk)) thunk)))
- (schedule-fiber! fiber thunk)))
+ "Resume @var{fiber}, adding it to the run queue of its scheduler.
+The fiber will start by applying @var{thunk}. A fiber @emph{must}
+only be resumed when it is suspended. This function is thread-safe
+even if @var{fiber} is running on a remote scheduler."
+ (let ((cont (fiber-continuation fiber)))
+ (unless cont (error "invalid fiber" fiber))
+ (schedule-fiber! fiber (lambda () (cont thunk)))))
(define (finalize-fd sched fd)
"Remove data associated with @var{fd} from the scheduler @var{ctx}.
@@ -304,6 +333,8 @@ from a finalizer thread."
(hashv-remove! sources-table fd))))
(define (add-fd-events! sched fd events fiber)
+ "Arrange to resume @var{fiber} when the file descriptor @var{fd} has
+the given @var{events}, expressed as an epoll bitfield."
(let ((sources (hashv-ref (scheduler-sources sched) fd)))
(cond
(sources
diff --git a/fibers/operations.scm b/fibers/operations.scm
index ae831a4..9537bb8 100644
--- a/fibers/operations.scm
+++ b/fibers/operations.scm
@@ -78,6 +78,10 @@
(base-ops choice-op-base-ops))
(define (wrap-operation op f)
+ "Given the operation @var{op}, return a new operation that, if and
+when it succeeds, will apply @var{f} to the values yielded by
+performing @var{op}, and yield the result as the values of the wrapped
+operation."
(match op
(($ <base-op> wrap-fn try-fn block-fn)
(make-base-operation (match wrap-fn
@@ -98,6 +102,9 @@
(make-choice-operation base-ops*)))))
(define (choose-operation . ops)
+ "Given the operations @var{ops}, return a new operation that if it
+succeeds, will succeed with one and only one of the sub-operations
+@var{ops}."
(define (flatten ops)
(match ops
(() '())
@@ -111,6 +118,8 @@
(base-ops (make-choice-operation (list->vector base-ops)))))
(define (perform-operation op)
+ "Perform the operation @var{op} and return the resulting values. If
+the operation cannot complete directly, block until it can complete."
(define (block)
(suspend-current-fiber
(lambda (fiber)
diff --git a/fibers/timers.scm b/fibers/timers.scm
index 14c9787..b4d8d16 100644
--- a/fibers/timers.scm
+++ b/fibers/timers.scm
@@ -27,6 +27,9 @@
#:replace (sleep))
(define (timer-operation expiry)
+ "Make an operation that will succeed when the current time is
+greater than or equal to @var{expiry}, expressed in internal time
+units. The operation will succeed with no values."
(make-base-operation #f
(lambda ()
(and (< expiry (get-internal-real-time))
@@ -42,10 +45,13 @@
expiry))))
(define (wait-operation seconds)
+ "Make an operation that will succeed with no values when
+@var{seconds} have elapsed."
(timer-operation
(+ (get-internal-real-time)
(inexact->exact
(round (* seconds internal-time-units-per-second))))))
(define (sleep seconds)
+ "Block the calling fiber until @var{seconds} have elapsed."
(perform-operation (wait-operation seconds)))