diff options
| author | Andy Wingo <wingo@pobox.com> | 2016-10-12 13:12:07 +0200 |
|---|---|---|
| committer | Andy Wingo <wingo@pobox.com> | 2016-10-12 13:12:07 +0200 |
| commit | 5ce060dcc898cd186b35bd3bef57f2dc3bf71a41 (patch) | |
| tree | 3051c84758a867d4699c14c867dc1f9209ddf81a | |
| parent | Epoll handles event buffer size itself (diff) | |
| download | guile-fibers-5ce060dcc898cd186b35bd3bef57f2dc3bf71a41.tar.gz | |
Update documentation.
| -rw-r--r-- | TODO.md | 22 | ||||
| -rw-r--r-- | fibers/channels.scm | 46 | ||||
| -rw-r--r-- | fibers/internal.scm | 39 | ||||
| -rw-r--r-- | fibers/operations.scm | 9 | ||||
| -rw-r--r-- | fibers/timers.scm | 6 |
5 files changed, 85 insertions, 37 deletions
@@ -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))) |
