Debian Codegraph @

lib/control/job.scm

raw
1 ;;;
2 ;;; control.job - common job description
3 ;;;
4 ;;; Copyright (c) 2010-2024 Shiro Kawai <[email protected]>
5 ;;;
6 ;;; Redistribution and use in source and binary forms, with or without
7 ;;; modification, are permitted provided that the following conditions
8 ;;; are met:
9 ;;;
10 ;;; 1. Redistributions of source code must retain the above copyright
11 ;;; notice, this list of conditions and the following disclaimer.
12 ;;;
13 ;;; 2. Redistributions in binary form must reproduce the above copyright
14 ;;; notice, this list of conditions and the following disclaimer in the
15 ;;; documentation and/or other materials provided with the distribution.
16 ;;;
17 ;;; 3. Neither the name of the authors nor the names of its contributors
18 ;;; may be used to endorse or promote products derived from this
19 ;;; software without specific prior written permission.
20 ;;;
21 ;;; THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 ;;; "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 ;;; LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24 ;;; A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 ;;; OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 ;;; SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
27 ;;; TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
28 ;;; PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
29 ;;; LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
30 ;;; NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
31 ;;; SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 ;;;
33
34 (define-module control.job
35 (use gauche.threads)
36 (use gauche.record)
37 (export
38 ;; API for end clients
39 job job? job-status job-result job-wait
40 job-acknowledge-time job-start-time job-finish-time
41 ;; API for control libraries
42 make-job job-touch! job-acknowledge! job-run! job-mark-killed!))
43 (select-module control.job)
44
45 ;; JOB is a common structure used by several control flow libraries
46 ;; The use of slots are up to those libraries, and generally the end
47 ;; user shouldn't care.
48 ;;
49 ;; A job can be used in three flavors w.r.t. multithread environemnt.
50 ;; 'waitable' - Threads can wait on a job to be finished.
51 ;; 'cancellable' - A job can be forcibly marked as 'killed' by a thread
52 ;; other than its runner. It doesn't guarantee that
53 ;; the runner thread stops immediately, but the job is
54 ;; regarded as finished. Waitable job is also cancellable,
55 ;; and waiting threads are waked up when the job is
56 ;; cancelled.
57 ;; bare - A job is neither cancellable nor waitable.
58 ;;
59 (define-record-type job %make-job #t
60 (thunk) ; the thing to do
61 (specific) ; library-specific data
62 (status) ; #f, acknowledged, running, done, error, killed.
63 (result) ; result of thunk, a condition, or the kill reason
64 (waiter-cv) ; wait on this cv for result change
65 (waiter-mutex) ; mutex to check result
66 (depends-on) ; list of jobs, when we track job dependency
67 (acknowledge-time) ; timestamp when this job is acknowledged
68 (start-time) ; timestamp when this job starts being executed
69 (finish-time)) ; timestamp when this job is finished
70
71 ;; API
72 (define (make-job thunk :key (specific #f) (waitable #f) (cancellable #f))
73 (%make-job thunk specific #f #f
74 (and waitable (make-condition-variable))
75 (and (or waitable cancellable) (make-mutex))
76 '() #f #f #f))
77
78 ;; API
79 (define (job-wait job :optional (timeout #f) (timeout-val #f))
80 (let ([mutex (job-waiter-mutex job)]
81 [cv (job-waiter-cv job)])
82 (unless (and mutex cv) (error "job is not waitable:" job))
83 (let loop ()
84 (mutex-lock! mutex)
85 (let1 s (job-status job)
86 (cond [(memq s '(done error killed)) (mutex-unlock! mutex) s]
87 [(mutex-unlock! mutex cv timeout) (loop)]
88 [else timeout-val])))))
89
90 ;; internal - caller must hold mutex lock if necessary
91 (define (%job-touch! job when :optional (now (current-time)))
92 (case when
93 [(:acknowledge) (job-acknowledge-time-set! job now)]
94 [(:start) (job-start-time-set! job now)]
95 [(:finish) (job-finish-time-set! job now)])
96 now)
97
98 ;; internal - common pattern
99 (define-syntax safely
100 (syntax-rules ()
101 [(_ job form ...)
102 (if-let1 mutex (job-waiter-mutex job)
103 (with-locking-mutex mutex (^[] form ...))
104 (begin form ...))]))
105
106 ;; API
107 (define (job-touch! job when :optional (now (current-time)))
108 (safely job (%job-touch! job when now)))
109
110 ;; API
111 (define (job-acknowledge! job)
112 (safely job
113 (%job-touch! job :acknowledge)
114 (job-status-set! job 'acknowledged)))
115
116 ;; API
117 (define (job-run! job)
118 (define (finish status result)
119 (if-let1 cv (job-waiter-cv job)
120 (condition-variable-broadcast! cv))
121 (unless (memq (job-status job) '(done error killed))
122 (%job-touch! job :finish)
123 (job-result-set! job result)
124 (job-status-set! job status)))
125 (define (start)
126 (and (not (eq? (job-status job) 'killed))
127 (begin (job-status-set! job 'running)
128 (%job-touch! job :start)
129 #t)))
130
131 (and (safely job (start))
132 (guard (e [else (safely job (finish 'error e))])
133 (let1 r ((job-thunk job))
134 (safely job (finish 'done r))))))
135
136 ;; this doesn't actually kill the process/threads that running the job,
137 ;; but merely marks the job killed and notify it to the waiter.
138 (define (job-mark-killed! job reason)
139 (let ([m (job-waiter-mutex job)]
140 [cv (job-waiter-cv job)])
141 (unless m (error "job is not cancellable:" job))
142 (with-locking-mutex m
143 (^[]
144 (%job-touch! job :finish)
145 (job-result-set! job reason)
146 (job-status-set! job 'killed)
147 (when cv
148 (condition-variable-broadcast! cv))))))