| @@ -0,0 +1,352 @@ |
| 1 | +/// A pool of connections (issue #145 §3): the pool actor hands out |
| 2 | +/// connections, one borrower at a time, and watches everyone it talks to |
| 3 | +/// — a dead borrower frees its connection (closed, not reused: its |
| 4 | +/// transaction state is unknown), a dead connection frees its slot. |
| 5 | +/// |
| 6 | +/// Waiting callers queue; the acquire timeout is the caller's |
| 7 | +/// (`acquire`'s), and a `CancelAcquire` best-effort message drops a |
| 8 | +/// request whose waiter gave up. |
| 9 | + |
| 10 | +import std/actor.{Continue, Stop} |
| 11 | +import std/list |
| 12 | +import std/option |
| 13 | +import std/process.{type Down, type Pid, type Subject, type proc, Down} |
| 14 | +import std/random.{type random} |
| 15 | +import std/result |
| 16 | +import std/string |
| 17 | + |
| 18 | +import client |
| 19 | +import config.{type Config} |
| 20 | + |
| 21 | +/// A pool of connections. |
| 22 | +pub opaque type Pool { |
| 23 | + Pool(Subject<Msg>) |
| 24 | +} |
| 25 | + |
| 26 | +/// The pool's messages. |
| 27 | +pub type Msg { |
| 28 | + /// Check a connection out; the answer is the connection's subject (or |
| 29 | + /// why not — connecting one failed). |
| 30 | + Acquire(borrower: Pid, reply: Subject<Result<Subject<client.Msg>, client.Error>>) |
| 31 | + /// A waiter that gave up; drop its queued request. |
| 32 | + CancelAcquire(borrower: Pid) |
| 33 | + /// Return a connection. |
| 34 | + Release(conn: Subject<client.Msg>) |
| 35 | +} |
| 36 | + |
| 37 | +/// What the pool's mailbox carries: its messages, and monitor reports. |
| 38 | +type Event { |
| 39 | + Ev(Msg) |
| 40 | + DownEv(Down) |
| 41 | +} |
| 42 | + |
| 43 | +type PoolState { |
| 44 | + PoolState( |
| 45 | + config: Config, |
| 46 | + size: Int, |
| 47 | + /// The pool's own subject. |
| 48 | + inbox: Subject<Msg>, |
| 49 | + /// Connections ready to hand out. |
| 50 | + idle: List<Subject<client.Msg>>, |
| 51 | + /// (borrower, connection) pairs. |
| 52 | + checked_out: List<(Pid, Subject<client.Msg>)>, |
| 53 | + /// Waiting borrowers, in order: (pid, its reply subject). |
| 54 | + waiting: List<(Pid, Subject<Result<Subject<client.Msg>, client.Error>>)>, |
| 55 | + /// Everyone watched: connection actors and borrowers. |
| 56 | + monitored: List<(Pid, Subject<Down>)>, |
| 57 | + ) |
| 58 | +} |
| 59 | + |
| 60 | +/// A pool of `size` connections, made now. The pool replaces dead |
| 61 | +/// connections as they're needed. |
| 62 | +pub fn start(config: Config, size: Int) -> Result<Pool, client.Error> / <io, proc, random> { |
| 63 | + use conns <- result.try(connect_all(config, size, [])) |
| 64 | + let ready = process.subject() |
| 65 | + { |
| 66 | + use <- process.spawn |
| 67 | + let inbox = process.subject() |
| 68 | + process.send(ready, inbox) |
| 69 | + serve(PoolState(config, size, inbox, conns, [], [], monitor_all(conns, []))) |
| 70 | + } |
| 71 | + Ok(Pool(process.receive_forever(ready))) |
| 72 | +} |
| 73 | + |
| 74 | +/// `size` connections, or the first failure. |
| 75 | +fn connect_all( |
| 76 | + config: Config, |
| 77 | + size: Int, |
| 78 | + acc: List<Subject<client.Msg>>, |
| 79 | +) -> Result<List<Subject<client.Msg>>, client.Error> / <io, proc, random> { |
| 80 | + if size <= 0 { |
| 81 | + Ok(list.reverse(acc)) |
| 82 | + } else { |
| 83 | + use conn <- result.try(client.connect(config)) |
| 84 | + connect_all(config, size - 1, [conn, ..acc]) |
| 85 | + } |
| 86 | +} |
| 87 | + |
| 88 | +// ---- the protocol (used by lib.lse) ------------------------------------------- |
| 89 | + |
| 90 | +/// A connection from the pool, or why not (nothing within the timeout). |
| 91 | +/// A grant that races a cancel is returned at once, never leaked. |
| 92 | +pub fn acquire(pool: Pool, timeout: Int) -> Result<Subject<client.Msg>, client.Error> / <proc> { |
| 93 | + let Pool(subject) = pool |
| 94 | + let me = process.self() |
| 95 | + let reply = process.subject() |
| 96 | + process.send(subject, Acquire(me, reply)) |
| 97 | + match process.receive(reply, timeout) { |
| 98 | + Some(answer) -> answer, |
| 99 | + None -> { |
| 100 | + actor.cast(subject, CancelAcquire(me)) |
| 101 | + match process.receive(reply, 0) { |
| 102 | + Some(Ok(conn)) -> { |
| 103 | + actor.cast(subject, Release(conn)) |
| 104 | + Error(client.Driver("no connection within the timeout")) |
| 105 | + }, |
| 106 | + _ -> Error(client.Driver("no connection within the timeout")), |
| 107 | + } |
| 108 | + } |
| 109 | + } |
| 110 | +} |
| 111 | + |
| 112 | +/// Return a connection to the pool. |
| 113 | +pub fn release(pool: Pool, conn: Subject<client.Msg>) -> () / <proc> { |
| 114 | + let Pool(subject) = pool |
| 115 | + actor.cast(subject, Release(conn)) |
| 116 | +} |
| 117 | + |
| 118 | +// ---- the actor ------------------------------------------------------------------ |
| 119 | + |
| 120 | +fn serve(state: PoolState) -> () / <proc, io, random> { |
| 121 | + let selector = selector_of(state.inbox, state.monitored) |
| 122 | + match handle_event(state, process.select_forever(selector)) { |
| 123 | + Continue(next) -> serve(next), |
| 124 | + Stop -> (), |
| 125 | + } |
| 126 | +} |
| 127 | + |
| 128 | +/// A selector over the pool's messages and every monitor report. |
| 129 | +fn selector_of(inbox: Subject<Msg>, monitored: List<(Pid, Subject<Down>)>) -> process.Selector<Event> { |
| 130 | + let base = process.new_selector() |> process.selecting(inbox, Ev) |
| 131 | + list.fold(monitored, base, fn(sel, entry) { process.selecting(sel, entry.1, DownEv) }) |
| 132 | +} |
| 133 | + |
| 134 | +fn handle_event(state: PoolState, event: Event) -> actor.Next<PoolState> / <io, proc, random> { |
| 135 | + match event { |
| 136 | + Ev(Acquire(borrower, reply)) -> Continue(grant_or_queue(state, borrower, reply)), |
| 137 | + Ev(CancelAcquire(borrower)) -> Continue(drop_waiter(state, borrower)), |
| 138 | + Ev(Release(conn)) -> Continue(returned(state, conn)), |
| 139 | + DownEv(down) -> Continue(stopped(state, down)), |
| 140 | + } |
| 141 | +} |
| 142 | + |
| 143 | +/// Answer an acquire: from the idle list, from a new connection (while |
| 144 | +/// under size), else queue the waiter. |
| 145 | +fn grant_or_queue( |
| 146 | + state: PoolState, |
| 147 | + borrower: Pid, |
| 148 | + reply: Subject<Result<Subject<client.Msg>, client.Error>>, |
| 149 | +) -> PoolState / <io, proc, random> { |
| 150 | + match state.idle { |
| 151 | + [conn, ..rest] -> grant(PoolState(..state, idle: rest), borrower, reply, conn), |
| 152 | + [] -> |
| 153 | + if live(state) < state.size { |
| 154 | + match client.connect(state.config) { |
| 155 | + Ok(conn) -> grant(state, borrower, reply, conn), |
| 156 | + Error(e) -> { |
| 157 | + process.send(reply, Error(e)) |
| 158 | + state |
| 159 | + } |
| 160 | + } |
| 161 | + } else { |
| 162 | + PoolState(..state, |
| 163 | + waiting: [..state.waiting, (borrower, reply)], |
| 164 | + monitored: watch(borrower, state.monitored), |
| 165 | + ) |
| 166 | + } |
| 167 | + } |
| 168 | +} |
| 169 | + |
| 170 | +/// Hand `conn` to `borrower`: watch the borrower, record the checkout, |
| 171 | +/// answer. |
| 172 | +fn grant( |
| 173 | + state: PoolState, |
| 174 | + borrower: Pid, |
| 175 | + reply: Subject<Result<Subject<client.Msg>, client.Error>>, |
| 176 | + conn: Subject<client.Msg>, |
| 177 | +) -> PoolState / <proc> { |
| 178 | + process.send(reply, Ok(conn)) |
| 179 | + PoolState(..state, |
| 180 | + checked_out: [(borrower, conn), ..state.checked_out], |
| 181 | + monitored: watch(conn.owner, watch(borrower, state.monitored)), |
| 182 | + ) |
| 183 | +} |
| 184 | + |
| 185 | +/// A returned connection answers the oldest waiter, or idles. |
| 186 | +fn returned(state: PoolState, conn: Subject<client.Msg>) -> PoolState / <proc> { |
| 187 | + let previous = owner_of(state.checked_out, conn) |
| 188 | + let state = PoolState(..state, |
| 189 | + checked_out: drop_conn(state.checked_out, conn), |
| 190 | + monitored: unwatch(previous, state.monitored), |
| 191 | + ) |
| 192 | + match state.waiting { |
| 193 | + [(borrower, reply), ..rest] -> |
| 194 | + grant(PoolState(..state, waiting: rest), borrower, reply, conn), |
| 195 | + [] -> PoolState(..state, idle: [conn, ..state.idle]), |
| 196 | + } |
| 197 | +} |
| 198 | + |
| 199 | +/// A monitor report: a stopped connection actor frees its slot; a stopped |
| 200 | +/// borrower frees its connection (closed, not reused) or its queue entry. |
| 201 | +fn stopped(state: PoolState, down: Down) -> PoolState / <io, proc, random> { |
| 202 | + let Down(pid, _) = down |
| 203 | + let state = PoolState(..state, monitored: drop_pid(state.monitored, pid)) |
| 204 | + match find_conn(state.checked_out, pid) { |
| 205 | + Some(conn) -> { |
| 206 | + // The borrower died holding it: its state is unknown, so close it. |
| 207 | + actor.cast(conn, client.Close(process.subject())) |
| 208 | + drain(PoolState(..state, checked_out: drop_pid(state.checked_out, pid))) |
| 209 | + }, |
| 210 | + None -> |
| 211 | + match find_owner(state.idle, pid) { |
| 212 | + Some(_) -> drain(PoolState(..state, idle: drop_owner(state.idle, pid))), |
| 213 | + None -> |
| 214 | + // A waiter's death only empties its queue entry. |
| 215 | + drain(PoolState(..state, waiting: drop_pid(state.waiting, pid))), |
| 216 | + }, |
| 217 | + } |
| 218 | +} |
| 219 | + |
| 220 | +/// A waiter gave up: drop its entry. |
| 221 | +fn drop_waiter(state: PoolState, borrower: Pid) -> PoolState { |
| 222 | + PoolState(..state, |
| 223 | + waiting: drop_pid(state.waiting, borrower), |
| 224 | + monitored: unwatch(Some(borrower), state.monitored), |
| 225 | + ) |
| 226 | +} |
| 227 | + |
| 228 | +/// Answer waiting callers while there is something to hand out. |
| 229 | +fn drain(state: PoolState) -> PoolState / <io, proc, random> { |
| 230 | + match state.waiting { |
| 231 | + [] -> state, |
| 232 | + [(borrower, reply), ..rest] -> |
| 233 | + match state.idle { |
| 234 | + [conn, ..idle] -> |
| 235 | + drain(grant(PoolState(..state, idle: idle, waiting: rest), borrower, reply, conn)), |
| 236 | + [] -> |
| 237 | + if live(state) < state.size { |
| 238 | + match client.connect(state.config) { |
| 239 | + Ok(conn) -> |
| 240 | + drain(grant(PoolState(..state, waiting: rest), borrower, reply, conn)), |
| 241 | + Error(e) -> { |
| 242 | + process.send(reply, Error(e)) |
| 243 | + drain(PoolState(..state, waiting: rest)) |
| 244 | + } |
| 245 | + } |
| 246 | + } else { |
| 247 | + state |
| 248 | + }, |
| 249 | + }, |
| 250 | + } |
| 251 | +} |
| 252 | + |
| 253 | +// ---- small helpers -------------------------------------------------------------- |
| 254 | + |
| 255 | +/// The connections out or idle (those are the live ones: a stopped |
| 256 | +/// connection actor's subject is removed on its Down). |
| 257 | +fn live(state: PoolState) -> Int { |
| 258 | + list.length(state.idle) + list.length(state.checked_out) |
| 259 | +} |
| 260 | + |
| 261 | +/// Watch `pid` (once). |
| 262 | +fn watch(pid: Pid, monitored: List<(Pid, Subject<Down>)>) -> List<(Pid, Subject<Down>)> / <proc> { |
| 263 | + if has_pid(monitored, pid) { |
| 264 | + monitored |
| 265 | + } else { |
| 266 | + [(pid, process.monitor(pid)), ..monitored] |
| 267 | + } |
| 268 | +} |
| 269 | + |
| 270 | +/// Stop watching `pid` (its subject stays in the mailbox; read no more). |
| 271 | +fn unwatch(pid: Option<Pid>, monitored: List<(Pid, Subject<Down>)>) -> List<(Pid, Subject<Down>)> { |
| 272 | + match pid { |
| 273 | + Some(pid) -> drop_pid(monitored, pid), |
| 274 | + None -> monitored, |
| 275 | + } |
| 276 | +} |
| 277 | + |
| 278 | +/// The connection whose owner's pid is `pid`. |
| 279 | +fn find_conn(list_: List<(Pid, Subject<client.Msg>)>, pid: Pid) -> Option<Subject<client.Msg>> { |
| 280 | + match list_ { |
| 281 | + [] -> None, |
| 282 | + [(p, conn), ..rest] -> if p == pid { Some(conn) } else { find_conn(rest, pid) }, |
| 283 | + } |
| 284 | +} |
| 285 | + |
| 286 | +/// The pid a connection is checked out to, by its owner pid. |
| 287 | +fn owner_of(entries: List<(Pid, Subject<client.Msg>)>, conn: Subject<client.Msg>) -> Option<Pid> { |
| 288 | + match entries { |
| 289 | + [] -> None, |
| 290 | + [(pid, c), ..rest] -> if c.owner == conn.owner { Some(pid) } else { owner_of(rest, conn) }, |
| 291 | + } |
| 292 | +} |
| 293 | + |
| 294 | +/// Drop the pair whose connection is `conn` (by its owner's pid). |
| 295 | +fn drop_conn(entries: List<(Pid, Subject<client.Msg>)>, conn: Subject<client.Msg>) -> List<(Pid, Subject<client.Msg>)> { |
| 296 | + match entries { |
| 297 | + [] -> [], |
| 298 | + [(p, c), ..rest] -> |
| 299 | + if c.owner == conn.owner { |
| 300 | + drop_conn(rest, conn) |
| 301 | + } else { |
| 302 | + [(p, c), ..drop_conn(rest, conn)] |
| 303 | + }, |
| 304 | + } |
| 305 | +} |
| 306 | + |
| 307 | +/// The subject whose owner is `pid`, in a bare subject list. |
| 308 | +fn find_owner(list_: List<Subject<client.Msg>>, pid: Pid) -> Option<Subject<client.Msg>> { |
| 309 | + match list_ { |
| 310 | + [] -> None, |
| 311 | + [c, ..rest] -> if c.owner == pid { Some(c) } else { find_owner(rest, pid) }, |
| 312 | + } |
| 313 | +} |
| 314 | + |
| 315 | +fn drop_owner(list_: List<Subject<client.Msg>>, pid: Pid) -> List<Subject<client.Msg>> { |
| 316 | + match list_ { |
| 317 | + [] -> [], |
| 318 | + [c, ..rest] -> |
| 319 | + if c.owner == pid { |
| 320 | + drop_owner(rest, pid) |
| 321 | + } else { |
| 322 | + [c, ..drop_owner(rest, pid)] |
| 323 | + }, |
| 324 | + } |
| 325 | +} |
| 326 | + |
| 327 | +fn drop_pid(entries: List<(Pid, a)>, pid: Pid) -> List<(Pid, a)> { |
| 328 | + match entries { |
| 329 | + [] -> [], |
| 330 | + [(p, v), ..rest] -> |
| 331 | + if p == pid { |
| 332 | + drop_pid(rest, pid) |
| 333 | + } else { |
| 334 | + [(p, v), ..drop_pid(rest, pid)] |
| 335 | + }, |
| 336 | + } |
| 337 | +} |
| 338 | + |
| 339 | +fn has_pid(entries: List<(Pid, a)>, pid: Pid) -> Bool { |
| 340 | + match entries { |
| 341 | + [] -> False, |
| 342 | + [(p, _), ..rest] -> p == pid || has_pid(rest, pid), |
| 343 | + } |
| 344 | +} |
| 345 | + |
| 346 | +/// Watch every connection's owner. |
| 347 | +fn monitor_all(conns: List<Subject<client.Msg>>, acc: List<(Pid, Subject<Down>)>) -> List<(Pid, Subject<Down>)> / <proc> { |
| 348 | + match conns { |
| 349 | + [] -> acc, |
| 350 | + [conn, ..rest] -> monitor_all(rest, watch(conn.owner, acc)), |
| 351 | + } |
| 352 | +} |