tobogganSe connecter

louise

Clone avec HTTPS, un jeton personnel en mot de passe, ou avec SSH, une clé ajoutée dans vos paramètres.

456 lignes · 11934 octetsBrut · Historique
1/// Supervisors: restart children that crash ("let it crash", ADR 0004),
2/// within a restart intensity, and stop them in order (ADR 0060).
3
4import std/list
5import std/os.{type Signal}
6import std/process.
7{ type ExitSignal
8, type Pid
9, type Subject
10, type proc
11, Crashed
12, ExitSignal
13, Normal
14, Shutdown
15}
16import std/random.{type random}
17import std/time.{type clock}
18
19pub type Strategy
20{ /// Restart only the child that crashed.
21 OneForOne
22 /// Restart every child when one crashes.
23, OneForAll
24 /// Restart the child that crashed and every child started after it
25 /// (they may depend on it); the ones before it keep running.
26, RestForOne
27}
28
29/// When a child is restarted (OTP's child kinds).
30@derive Eq Show
31pub type Restart
32{ /// Always: after it crashes, and after it returns.
33 Permanent
34 /// After it crashes only: a child that returns (or is stopped with
35 /// `Shutdown`) is done.
36, Transient
37 /// Never.
38, Temporary
39}
40
41/// How to start a child. The child is linked to its supervisor.
42pub type Child
43{ /// Restarted after a crash only (`Transient`), given 5 seconds to stop.
44 Child(name: String, start: send fn() -> () / <proc, clock, random, io, ffi>)
45 /// Restarted as `restart` says, given `shutdown_timeout` milliseconds to
46 /// stop when its supervisor shuts down (then killed).
47, ChildWith(
48 name: String
49 , start: send fn() -> () / <proc, clock, random, io, ffi>
50 , restart: Restart
51 , shutdown_timeout: Int
52 )
53}
54
55/// A supervisor: its children, started in order, its strategy, and its
56/// restart intensity: more than `intensity` restarts within `period_ms`
57/// milliseconds make it give up (crash). A negative `period_ms` counts
58/// restarts over the supervisor's whole life.
59pub type Spec
60{ Spec(
61 strategy: Strategy
62 , children: List<Child>
63 , intensity: Int
64 , period_ms: Int
65 )
66}
67
68/// Run a supervisor in the current actor: start the children, restart
69/// them as `strategy` and their kinds say, and crash itself after
70/// `max_restarts` restarts (over its whole life; `run` takes a window).
71/// Returns when every child is done.
72pub fn supervise ::
73 strategy: Strategy
74 children: List<Child>
75 max_restarts: Int
76 -> () / <proc, io>
77{
78 // Over its whole life: no clock needed.
79 run_with Spec(strategy, children, max_restarts, -1) fn { 0 }
80}
81
82/// Run the supervisor `spec` in the current actor (see `Spec`). It traps
83/// exits: told to stop (`process.stop`, a `Shutdown` exit signal), it
84/// stops its children in reverse start order, each with `Shutdown` and
85/// killed after its `shutdown_timeout`, then returns. Returns too when
86/// every child is done.
87pub fn run :: spec: Spec -> () / <proc, io, clock>
88{
89 run_with spec now_ms
90}
91
92/// The monotonic clock, in milliseconds.
93fn now_ms :: -> Int / <clock>
94{
95 time.in_milliseconds (time.monotonic ())
96}
97
98/// `run`, reading the time from `now` (for the restart window).
99fn run_with :: spec: Spec now: fn() -> Int / <e> -> () / <proc, io | e>
100{
101 process.trap_exits True
102 let exits = process.exits ()
103 watch spec exits (list.map spec.children start_child) [] now
104}
105
106type Running = List<(Pid, Child)>
107
108fn start_child :: child: Child -> (Pid, Child) / <proc>
109{
110 (process.spawn_link (start_of child), child)
111}
112
113fn start_of :: child: Child -> send fn() -> () / <proc, clock, random, io, ffi>
114{
115 match child { Child(_, start) -> start, ChildWith(_, start, _, _) -> start }
116}
117
118fn restart_of :: child: Child -> Restart
119{
120 match child
121 { Child(_, _) -> Transient, ChildWith(_, _, restart, _) -> restart }
122}
123
124fn shutdown_timeout_of :: child: Child -> Int
125{
126 match child { Child(_, _) -> 5000, ChildWith(_, _, _, timeout) -> timeout }
127}
128
129/// `restarts`: when the restarts within the window happened (`now`'s
130/// milliseconds, the latest first).
131fn watch ::
132 spec: Spec
133 exits: Subject<ExitSignal>
134 running: Running
135 restarts: List<Int>
136 now: fn() -> Int / <e>
137 -> () / <proc, io | e>
138{
139 match running
140 { [] -> ()
141 , _ ->
142 {
143 let ExitSignal(pid, reason) = process.receive_forever exits
144 if !is_running running pid
145 {
146 if reason == Shutdown
147 {
148 // Told to stop, by whoever started it.
149 shutdown running exits
150 }
151 else
152 {
153 // A child replaced or killed by a restart: already handled.
154 watch spec exits running restarts now
155 }
156 }
157 else
158 {
159 let child = child_of running pid
160 let done = match (restart_of child, reason)
161 { (Temporary, _) -> True
162 , (Transient, Normal) -> True
163 , (Transient, Shutdown) -> True
164 , _ -> False
165 }
166 if done
167 {
168 watch spec exits (remove running pid) restarts now
169 }
170 else
171 {
172 let restarts = counted restarts spec.period_ms (now ())
173 if list.length restarts > spec.intensity
174 {
175 // Stop the others (the crashed child is gone already).
176 shutdown (remove running pid) exits
177 panic "supervisor: too many restarts"
178 }
179 else
180 {
181 let restarted = match spec.strategy
182 { OneForOne -> restart_one running pid
183 , OneForAll -> restart_all running
184 , RestForOne -> restart_rest running pid
185 }
186 watch spec exits restarted restarts now
187 }
188 }
189 }
190 }
191 }
192}
193
194/// `restarts` with one more `now`, forgetting those older than
195/// `period_ms` (none if it is negative).
196fn counted :: restarts: List<Int> period_ms: Int now: Int -> List<Int>
197{
198 let recent = if period_ms < 0
199 {
200 restarts
201 }
202 else
203 {
204 list.filter restarts fn t { now - t < period_ms }
205 }
206 [now, ..recent]
207}
208
209fn is_running :: running: Running pid: Pid -> Bool
210{
211 use found, entry <- list.fold running False
212 found || entry.0 == pid
213}
214
215fn child_of :: running: Running pid: Pid -> Child
216{
217 match running
218 { [] -> panic "supervisor: not a child"
219 , [entry, ..rest] -> if entry.0 == pid { entry.1 } else { child_of rest pid }
220 }
221}
222
223fn remove :: running: Running pid: Pid -> Running
224{
225 use entry <- list.filter running
226 entry.0 != pid
227}
228
229fn restart_one :: running: Running pid: Pid -> Running / <proc>
230{
231 use entry <- list.map running
232 if entry.0 == pid
233 {
234 start_child entry.1
235 }
236 else
237 {
238 entry
239 }
240}
241
242fn restart_all :: running: Running -> Running / <proc>
243{
244 list.each running fn entry { process.kill entry.0 }
245 restart_kept running
246}
247
248/// Restart `pid` and the children after it, in order; the later ones are
249/// stopped first.
250fn restart_rest :: running: Running pid: Pid -> Running / <proc>
251{
252 match running
253 { [] -> []
254 , [ entry
255 , ..rest
256 ] -> if entry.0 == pid
257 {
258 // Stop the later children last-started first, as OTP does.
259 list.each (list.reverse rest) fn later { process.kill later.0 }
260 restart_kept [entry, ..rest]
261 }
262 else
263 {
264 [entry, ..restart_rest rest pid]
265 }
266 }
267}
268
269/// Start `running`'s children again, but the temporary ones, which are
270/// done.
271fn restart_kept :: running: Running -> Running / <proc>
272{
273 let kept = list.filter running fn entry { restart_of entry.1 != Temporary }
274 list.map kept fn entry { start_child entry.1 }
275}
276
277/// Stop every child, last-started first: each with `Shutdown`, killed if
278/// it is not done within its `shutdown_timeout`.
279fn shutdown :: running: Running exits: Subject<ExitSignal> -> () / <proc>
280{
281 let _ =
282 list.fold
283 (list.reverse running)
284 []
285 fn gone entry
286 {
287 stop_child entry.0 (shutdown_timeout_of entry.1) exits gone
288 }
289 ()
290}
291
292/// Stop `pid`, waiting up to `timeout` milliseconds for its exit signal,
293/// then kill it and wait for it. `gone`: the children whose exit signals
294/// arrived meanwhile (each arrives once); returns it updated.
295fn stop_child ::
296 pid: Pid
297 timeout: Int
298 exits: Subject<ExitSignal>
299 gone: List<Pid>
300 -> List<Pid> / <proc>
301{
302 if list.any gone fn p { p == pid }
303 {
304 gone
305 }
306 else
307 {
308 process.stop pid
309 match wait_exit pid timeout exits gone
310 { (True, gone) -> gone
311 , (False, gone) ->
312 {
313 process.kill pid
314 (wait_exit pid (-1) exits gone).1
315 }
316 }
317 }
318}
319
320/// Wait up to `timeout` milliseconds (negative: forever) for `pid`'s exit
321/// signal: whether it came, and the other children that exited meanwhile.
322fn wait_exit ::
323 pid: Pid
324 timeout: Int
325 exits: Subject<ExitSignal>
326 gone: List<Pid>
327 -> (Bool, List<Pid>) / <proc>
328{
329 match process.receive exits timeout
330 { None -> (False, gone)
331 , Some(ExitSignal(from, _)) -> if from == pid
332 {
333 (True, gone)
334 }
335 else
336 {
337 wait_exit pid timeout exits [from, ..gone]
338 }
339 }
340}
341
342/// How the runtime supervises a program's `main` (ADR 0060): the
343/// `[application]` section of `louise.toml`. `main` is restarted as
344/// `restart` says after it crashes, at most `intensity` times within
345/// `period_ms` milliseconds; on one of `signals`, it is stopped
346/// (`Shutdown`), and killed if it is not done within `shutdown_timeout_ms`.
347pub type Application
348{ Application(
349 restart: Restart
350 , intensity: Int
351 , period_ms: Int
352 , shutdown_timeout_ms: Int
353 , signals: List<Signal>
354 )
355}
356
357/// Run `main` under `app` (the program's root when `louise.toml` has an
358/// `[application]` section; the compiler generates the call). Returns,
359/// and the program exits 0, when `main` returns, or once it stopped after
360/// a signal; a crash beyond the restart intensity (or any crash, for a
361/// `Temporary` main) ends the program with that panic.
362pub fn application ::
363 app: Application
364 main: send fn() -> () / <proc, clock, random, io, ffi>
365 -> () / <proc, io, clock>
366{
367 process.trap_exits True
368 let exits = process.exits ()
369 let signals = os.signals app.signals
370 let events =
371 process.new_selector ()
372 |> process.selecting exits Exited
373 |> process.selecting signals Signalled
374 supervise_main app main events (process.spawn_link main) []
375}
376
377/// What `application` waits for.
378type MainEvent { Exited(ExitSignal), Signalled(Signal) }
379
380fn supervise_main ::
381 app: Application
382 main: send fn() -> () / <proc, clock, random, io, ffi>
383 events: process.Selector<MainEvent>
384 pid: Pid
385 restarts: List<Int>
386 -> () / <proc, io, clock>
387{
388 match process.select_forever events
389 { Signalled(_) -> stop_main pid app.shutdown_timeout_ms events
390 , Exited
391 ( ExitSignal(from, reason)
392 ) -> if from != pid
393 {
394 // Another linked actor: not `main`'s business here.
395 supervise_main app main events pid restarts
396 }
397 else
398 {
399 match (app.restart, reason)
400 { (_, Normal) -> ()
401 , (_, Shutdown) -> ()
402 , (Temporary, _) -> panic (crash_message reason)
403 , _ ->
404 {
405 let restarts = counted restarts app.period_ms (now_ms ())
406 if list.length restarts > app.intensity
407 {
408 panic (crash_message reason)
409 }
410 else
411 {
412 supervise_main app main events (process.spawn_link main) restarts
413 }
414 }
415 }
416 }
417 }
418}
419
420fn crash_message :: reason: process.ExitReason -> String
421{
422 match reason { Crashed(message) -> message, _ -> "main was killed" }
423}
424
425/// Stop `main` (`Shutdown`), waiting up to `timeout` milliseconds for it,
426/// then kill it. Further signals meanwhile are ignored.
427fn stop_main ::
428 pid: Pid
429 timeout: Int
430 events: process.Selector<MainEvent>
431 -> () / <proc>
432{
433 process.stop pid
434 if !main_exited pid timeout events
435 {
436 process.kill pid
437 let _ = main_exited pid (-1) events
438 }
439}
440
441/// Whether `main` (`pid`) exited within `timeout` milliseconds (negative:
442/// forever).
443fn main_exited ::
444 pid: Pid
445 timeout: Int
446 events: process.Selector<MainEvent>
447 -> Bool / <proc>
448{
449 match process.select events timeout
450 { None -> False
451 , Some
452 ( Exited(ExitSignal(from, _))
453 ) -> if from == pid { True } else { main_exited pid timeout events }
454 , Some(Signalled(_)) -> main_exited pid timeout events
455 }
456}