louise
The Louise language: compiler, runtime, std, tooling
Clone avec HTTPS, un jeton personnel en mot de passe, ou avec SSH, une clé ajoutée dans vos paramètres.
Dernier runRéussi#88 · main · 15 min 30 s
0Étoiles
0Forks
40Issues
| 1 | /// Supervisors: restart children that crash ("let it crash", ADR 0004), |
| 2 | /// within a restart intensity, and stop them in order (ADR 0060). |
| 3 | |
| 4 | import std/list |
| 5 | import std/os.{type Signal} |
| 6 | import std/process. |
| 7 | { type ExitSignal |
| 8 | , type Pid |
| 9 | , type Subject |
| 10 | , type proc |
| 11 | , Crashed |
| 12 | , ExitSignal |
| 13 | , Normal |
| 14 | , Shutdown |
| 15 | } |
| 16 | import std/random.{type random} |
| 17 | import std/time.{type clock} |
| 18 | |
| 19 | pub 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 |
| 31 | pub 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. |
| 42 | pub 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. |
| 59 | pub 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. |
| 72 | pub 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. |
| 87 | pub fn run :: spec: Spec -> () / <proc, io, clock> |
| 88 | { |
| 89 | run_with spec now_ms |
| 90 | } |
| 91 | |
| 92 | /// The monotonic clock, in milliseconds. |
| 93 | fn now_ms :: -> Int / <clock> |
| 94 | { |
| 95 | time.in_milliseconds (time.monotonic ()) |
| 96 | } |
| 97 | |
| 98 | /// `run`, reading the time from `now` (for the restart window). |
| 99 | fn 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 | |
| 106 | type Running = List<(Pid, Child)> |
| 107 | |
| 108 | fn start_child :: child: Child -> (Pid, Child) / <proc> |
| 109 | { |
| 110 | (process.spawn_link (start_of child), child) |
| 111 | } |
| 112 | |
| 113 | fn start_of :: child: Child -> send fn() -> () / <proc, clock, random, io, ffi> |
| 114 | { |
| 115 | match child { Child(_, start) -> start, ChildWith(_, start, _, _) -> start } |
| 116 | } |
| 117 | |
| 118 | fn restart_of :: child: Child -> Restart |
| 119 | { |
| 120 | match child |
| 121 | { Child(_, _) -> Transient, ChildWith(_, _, restart, _) -> restart } |
| 122 | } |
| 123 | |
| 124 | fn 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). |
| 131 | fn 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). |
| 196 | fn 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 | |
| 209 | fn is_running :: running: Running pid: Pid -> Bool |
| 210 | { |
| 211 | use found, entry <- list.fold running False |
| 212 | found || entry.0 == pid |
| 213 | } |
| 214 | |
| 215 | fn 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 | |
| 223 | fn remove :: running: Running pid: Pid -> Running |
| 224 | { |
| 225 | use entry <- list.filter running |
| 226 | entry.0 != pid |
| 227 | } |
| 228 | |
| 229 | fn 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 | |
| 242 | fn 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. |
| 250 | fn 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. |
| 271 | fn 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`. |
| 279 | fn 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. |
| 295 | fn 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. |
| 322 | fn 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`. |
| 347 | pub 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. |
| 362 | pub 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. |
| 378 | type MainEvent { Exited(ExitSignal), Signalled(Signal) } |
| 379 | |
| 380 | fn 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 | |
| 420 | fn 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. |
| 427 | fn 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). |
| 443 | fn 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 | } |