mini_racer_rs 1.2.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,811 @@
1
+ use std::cell::{Cell, OnceCell, RefCell};
2
+ use std::collections::VecDeque;
3
+
4
+ use magnus::error::ErrorType;
5
+ use magnus::gc::Marker;
6
+ use magnus::scan_args::{get_kwargs, scan_args};
7
+ use magnus::typed_data::Obj;
8
+ use magnus::value::ReprValue;
9
+ use magnus::{
10
+ Class, DataTypeFunctions, Error, Exception, ExceptionClass, Integer, KwArgs, Module, RArray,
11
+ RClass, RHash, RModule, Ruby, TypedData, Value, kwargs,
12
+ };
13
+ use mini_racer_engine::process::fork;
14
+
15
+ use crate::context::{self, Context};
16
+ use crate::gc_root::{self, OnceRoot, OwnedRoot};
17
+ use crate::options::{self, OptionValue};
18
+ use crate::{errors, export, rb_raw};
19
+
20
+ const SHUT_DOWN: &str = "the context pool is shut down";
21
+ // How long a waiting checkout sleeps before it looks at the slots again
22
+ // unwoken: a checkout that ended in a break, a throw or Thread#kill leaves its
23
+ // context idle without handing it on.
24
+ const RESCAN_SECONDS: f64 = 0.1;
25
+
26
+ static SHUTDOWN_ERROR: OnceRoot<ExceptionClass> = OnceRoot::new();
27
+
28
+ #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
29
+ enum Phase {
30
+ // Waiting for a thread of the pool's own to dispose the context it holds,
31
+ // if any, and build a new one.
32
+ #[default]
33
+ Pending,
34
+ Building,
35
+ Idle,
36
+ // Handed to the waiting checkout whose queue `holder` holds.
37
+ Reserved,
38
+ InUse,
39
+ // The last build raised; the next checkout raises that and starts another.
40
+ Failed,
41
+ Closed,
42
+ }
43
+
44
+ #[derive(Default)]
45
+ struct Slot {
46
+ phase: Cell<Phase>,
47
+ // The context while idle, in use or pending disposal; the exception while
48
+ // failed.
49
+ value: OwnedRoot<Value>,
50
+ // The fiber that checked the context out, whose nested checkouts reuse
51
+ // it, or the queue of the waiting checkout it is reserved for.
52
+ holder: OwnedRoot<Value>,
53
+ // The fiber of the waiting checkout it is reserved for.
54
+ waiter: OwnedRoot<Value>,
55
+ uses: Cell<u64>,
56
+ spent: Cell<bool>,
57
+ }
58
+
59
+ #[derive(Default)]
60
+ struct Waiter {
61
+ queue: OwnedRoot<Value>,
62
+ fiber: OwnedRoot<Value>,
63
+ }
64
+
65
+ /// `MiniRacerRs::Pool`: contexts built ahead, checked out one per fiber, and
66
+ /// replaced on threads of the pool's own. Only touched under the GVL.
67
+ #[derive(Default, TypedData)]
68
+ #[magnus(
69
+ class = "MiniRacerRs::Pool",
70
+ name = "mini_racer_rs/pool",
71
+ free_immediately,
72
+ mark
73
+ )]
74
+ pub struct Pool {
75
+ slots: OnceCell<Box<[Slot]>>,
76
+ max_uses: Cell<Option<u64>>,
77
+ options: OwnedRoot<RHash>,
78
+ setup: OwnedRoot<Value>,
79
+ // Waiting checkouts in arrival order, each by a Thread::Queue of its own
80
+ // that it pops, which parks a fiber under a scheduler and the thread
81
+ // otherwise. A freed context goes to the first of them, and a checkout
82
+ // that finds any waiting waits behind them, so none is passed over.
83
+ waiting: RefCell<VecDeque<Waiter>>,
84
+ // Queues of waits a trap handler's checkout displaced, owed a wakeup.
85
+ owed: RefCell<Vec<OwnedRoot<Value>>>,
86
+ epoch: Cell<u64>,
87
+ shut_down: Cell<bool>,
88
+ }
89
+
90
+ impl DataTypeFunctions for Pool {
91
+ fn mark(&self, marker: &Marker) {
92
+ self.options.mark(marker);
93
+ self.setup.mark(marker);
94
+ // As for gc_root::Pins: a borrow at mark time would leave a queue
95
+ // unmarked, and no borrow spans a Ruby call.
96
+ let Ok(waiting) = self.waiting.try_borrow() else {
97
+ std::process::abort();
98
+ };
99
+ for waiter in waiting.iter() {
100
+ waiter.queue.mark(marker);
101
+ waiter.fiber.mark(marker);
102
+ }
103
+ let Ok(owed) = self.owed.try_borrow() else {
104
+ std::process::abort();
105
+ };
106
+ for queue in owed.iter() {
107
+ queue.mark(marker);
108
+ }
109
+ for slot in self.slots.get().iter().flat_map(|slots| slots.iter()) {
110
+ slot.value.mark(marker);
111
+ slot.holder.mark(marker);
112
+ slot.waiter.mark(marker);
113
+ }
114
+ }
115
+ }
116
+
117
+ pub fn init(ruby: &Ruby, rs: RModule) -> Result<(), Error> {
118
+ let class = rs.define_class("Pool", ruby.class_object())?;
119
+ class.define_alloc_func::<Pool>();
120
+ class.define_method("initialize", export!(method Pool::initialize, -1))?;
121
+ class.define_method("with", export!(method Pool::with, 0))?;
122
+ class.define_method("shutdown", export!(method Pool::shutdown, 0))?;
123
+ let base: RClass = ruby
124
+ .class_object()
125
+ .const_get::<_, RModule>("MiniRacer")?
126
+ .const_get("Error")?;
127
+ let error = class.define_class("ShutdownError", base)?;
128
+ if let Some(error) = ExceptionClass::from_value(error.as_value()) {
129
+ SHUTDOWN_ERROR.set(ruby, error);
130
+ }
131
+ Ok(())
132
+ }
133
+
134
+ fn uninitialized(ruby: &Ruby) -> Error {
135
+ errors::internal(ruby, "pool is not initialized")
136
+ }
137
+
138
+ fn shut_down(ruby: &Ruby) -> Error {
139
+ SHUTDOWN_ERROR.get(ruby).map_or_else(
140
+ || errors::internal(ruby, SHUT_DOWN),
141
+ |class| Error::new(class, SHUT_DOWN),
142
+ )
143
+ }
144
+
145
+ // After a captured break, throw or Thread#kill, Ruby resumes from what the
146
+ // execution context holds, which a Ruby call could overwrite.
147
+ fn jumped(error: &Error) -> bool {
148
+ matches!(error.error_type(), ErrorType::Jump(_))
149
+ }
150
+
151
+ fn dispose(context: Value) -> Result<(), Error> {
152
+ context.funcall::<_, _, Value>("dispose", ()).map(drop)
153
+ }
154
+
155
+ // As `Context.new` reads its integers, except that a Bignum is out of range
156
+ // rather than of the wrong type.
157
+ fn limit_value(ruby: &Ruby, value: Value) -> Result<OptionValue, Error> {
158
+ Ok(match context::option_value(ruby, value) {
159
+ OptionValue::Other(_) if Integer::from_value(value).is_some() => {
160
+ if value.funcall::<_, _, bool>("negative?", ())? {
161
+ OptionValue::Fixnum(i64::MIN)
162
+ } else {
163
+ OptionValue::Fixnum(i64::MAX)
164
+ }
165
+ }
166
+ other => other,
167
+ })
168
+ }
169
+
170
+ fn thread_queue(ruby: &Ruby) -> Result<Value, Error> {
171
+ ruby.class_object()
172
+ .const_get::<_, RClass>("Thread")?
173
+ .const_get::<_, RClass>("Queue")?
174
+ .new_instance(())
175
+ }
176
+
177
+ impl Pool {
178
+ fn slots(&self, ruby: &Ruby) -> Result<&[Slot], Error> {
179
+ self.slots
180
+ .get()
181
+ .map(|slots| &**slots)
182
+ .ok_or_else(|| uninitialized(ruby))
183
+ }
184
+
185
+ fn slot(&self, index: usize) -> Option<&Slot> {
186
+ self.slots.get().and_then(|slots| slots.get(index))
187
+ }
188
+
189
+ fn initialize(ruby: &Ruby, rb_self: Obj<Self>, args: &[Value]) -> Result<(), Error> {
190
+ if rb_self.slots.get().is_some() {
191
+ return Err(errors::internal(ruby, "pool is already initialized"));
192
+ }
193
+ let args = scan_args::<(), (), (), (), RHash, ()>(args)?;
194
+ let keywords = ruby.hash_new();
195
+ keywords.update(args.keywords)?;
196
+ let keywords =
197
+ get_kwargs::<_, (Value,), (Option<Value>,), RHash>(keywords, &["size"], &["max_uses"])?;
198
+ let (size,) = keywords.required;
199
+ let (max_uses,) = keywords.optional;
200
+ let max_uses = match max_uses {
201
+ Some(value) => limit_value(ruby, value)?,
202
+ None => OptionValue::Nil,
203
+ };
204
+ let limits = options::pool(&limit_value(ruby, size)?, &max_uses)
205
+ .map_err(|error| context::option_error(ruby, &error))?;
206
+ let options = keywords.splat;
207
+ options.freeze();
208
+ rb_self.options.set(ruby, options);
209
+ if ruby.block_given() {
210
+ rb_self.setup.set(ruby, ruby.block_proc()?.as_value());
211
+ }
212
+ rb_self.max_uses.set(limits.max_uses);
213
+ rb_self.epoch.set(fork::epoch());
214
+ let slots = rb_self.slots.get_or_init(|| {
215
+ (0..limits.size)
216
+ .map(|_| Slot {
217
+ phase: Cell::new(Phase::Building),
218
+ ..Slot::default()
219
+ })
220
+ .collect()
221
+ });
222
+ for slot in slots {
223
+ match rb_self.build(ruby) {
224
+ Ok(context) => {
225
+ slot.value.set(ruby, context);
226
+ slot.phase.set(Phase::Idle);
227
+ }
228
+ Err(error) => {
229
+ rb_self.abandon(ruby, &error);
230
+ return Err(error);
231
+ }
232
+ }
233
+ }
234
+ Ok(())
235
+ }
236
+
237
+ // A pool whose first contexts did not all build disposes those that did.
238
+ fn abandon(&self, ruby: &Ruby, error: &Error) {
239
+ self.shut_down.set(true);
240
+ for slot in self.slots.get().iter().flat_map(|slots| slots.iter()) {
241
+ slot.phase.set(Phase::Closed);
242
+ if let Some(context) = slot.value.take(ruby)
243
+ && !jumped(error)
244
+ {
245
+ let _ = dispose(context);
246
+ }
247
+ }
248
+ }
249
+
250
+ // The setup block runs for every context, replacements included.
251
+ fn build(&self, ruby: &Ruby) -> Result<Value, Error> {
252
+ let options = self.options.get(ruby).ok_or_else(|| uninitialized(ruby))?;
253
+ let context: Value = Context::class(ruby).funcall("new", (KwArgs(options),))?;
254
+ let Some(setup) = self.setup.get(ruby) else {
255
+ return Ok(context);
256
+ };
257
+ match setup.funcall::<_, _, Value>("call", (context,)) {
258
+ Ok(_) => Ok(context),
259
+ Err(error) => {
260
+ if !jumped(&error) {
261
+ let _ = dispose(context);
262
+ }
263
+ Err(error)
264
+ }
265
+ }
266
+ }
267
+
268
+ fn refuse_if_shut_down(&self, ruby: &Ruby) -> Result<(), Error> {
269
+ if self.shut_down.get() {
270
+ Err(shut_down(ruby))
271
+ } else {
272
+ Ok(())
273
+ }
274
+ }
275
+
276
+ // A forked child forgets every context its parent built, disposing none,
277
+ // since they belong to the parent's runners, and builds its own; the
278
+ // checkouts that waited there are gone with the parent's other threads.
279
+ fn reconcile(&self, ruby: &Ruby) {
280
+ let epoch = fork::epoch();
281
+ if self.epoch.replace(epoch) == epoch {
282
+ return;
283
+ }
284
+ let phase = if self.shut_down.get() {
285
+ Phase::Closed
286
+ } else {
287
+ Phase::Pending
288
+ };
289
+ for slot in self.slots.get().iter().flat_map(|slots| slots.iter()) {
290
+ slot.value.take(ruby);
291
+ slot.holder.take(ruby);
292
+ slot.waiter.take(ruby);
293
+ slot.uses.set(0);
294
+ slot.spent.set(false);
295
+ slot.phase.set(phase);
296
+ }
297
+ self.waiting.borrow_mut().clear();
298
+ self.owed.borrow_mut().clear();
299
+ }
300
+
301
+ // The first waiting checkout's queue and fiber.
302
+ fn first_waiting(&self, ruby: &Ruby) -> Option<(Value, Value)> {
303
+ let waiting = self.waiting.borrow();
304
+ let first = waiting.front()?;
305
+ Some((first.queue.get(ruby)?, first.fiber.get(ruby)?))
306
+ }
307
+
308
+ fn enlist(&self, ruby: &Ruby, queue: Value, fiber: Value) {
309
+ let waiter = Waiter::default();
310
+ waiter.queue.set(ruby, queue);
311
+ waiter.fiber.set(ruby, fiber);
312
+ self.waiting.borrow_mut().push_back(waiter);
313
+ }
314
+
315
+ fn delist(&self, ruby: &Ruby, queue: Value) -> bool {
316
+ let mut waiting = self.waiting.borrow_mut();
317
+ let found = waiting.iter().position(|waiter| {
318
+ waiter
319
+ .queue
320
+ .get(ruby)
321
+ .is_some_and(|listed| same(listed, queue))
322
+ });
323
+ found.and_then(|index| waiting.remove(index)).is_some()
324
+ }
325
+
326
+ fn replace_waiting(&self, ruby: &Ruby, outer: Value, queue: Value) {
327
+ let waiting = self.waiting.borrow();
328
+ let listed = waiting.iter().find(|waiter| {
329
+ waiter
330
+ .queue
331
+ .get(ruby)
332
+ .is_some_and(|listed| same(listed, outer))
333
+ });
334
+ if let Some(waiter) = listed {
335
+ waiter.queue.set(ruby, queue);
336
+ }
337
+ }
338
+
339
+ // The queue of a wait `fiber` already has, in line or with a context
340
+ // reserved for it.
341
+ fn place_of(&self, ruby: &Ruby, fiber: Value) -> Option<Value> {
342
+ let listed = self.waiting.borrow().iter().find_map(|waiter| {
343
+ waiter
344
+ .fiber
345
+ .get(ruby)
346
+ .is_some_and(|listed| same(listed, fiber))
347
+ .then(|| waiter.queue.get(ruby))
348
+ .flatten()
349
+ });
350
+ listed.or_else(|| {
351
+ self.slots.get()?.iter().find_map(|slot| {
352
+ (slot.phase.get() == Phase::Reserved
353
+ && slot
354
+ .waiter
355
+ .get(ruby)
356
+ .is_some_and(|waiter| same(waiter, fiber)))
357
+ .then(|| slot.holder.get(ruby))
358
+ .flatten()
359
+ })
360
+ })
361
+ }
362
+
363
+ fn reserved_for(&self, ruby: &Ruby, queue: Value) -> Option<(usize, &Slot)> {
364
+ self.slots.get()?.iter().enumerate().find(|(_, slot)| {
365
+ slot.phase.get() == Phase::Reserved
366
+ && slot
367
+ .holder
368
+ .get(ruby)
369
+ .is_some_and(|holder| same(holder, queue))
370
+ })
371
+ }
372
+
373
+ // A nested checkout on the fiber that holds a context gets that context,
374
+ // so it cannot wait on itself, and a callback that reenters the pool runs
375
+ // on the context already running it.
376
+ fn with(ruby: &Ruby, rb_self: Obj<Self>) -> Result<Value, Error> {
377
+ if !ruby.block_given() {
378
+ return Err(Error::new(
379
+ ruby.exception_local_jump_error(),
380
+ "no block given (yield)",
381
+ ));
382
+ }
383
+ let slots = rb_self.slots(ruby)?;
384
+ rb_self.reconcile(ruby);
385
+ rb_self.refuse_if_shut_down(ruby)?;
386
+ let fiber = ruby.fiber_current().as_value();
387
+ let held = slots.iter().find(|slot| {
388
+ slot.phase.get() == Phase::InUse
389
+ && slot
390
+ .holder
391
+ .get(ruby)
392
+ .is_some_and(|holder| same(holder, fiber))
393
+ });
394
+ if let Some(slot) = held {
395
+ return Self::nested(ruby, slot);
396
+ }
397
+ let (index, context, displaced) = rb_self.checkout(ruby, rb_self, fiber)?;
398
+ let epoch = fork::epoch();
399
+ let result = rb_raw::yield_ensuring(ruby, context, &mut |ruby, raised| {
400
+ rb_self.checkin(ruby, index, epoch, raised);
401
+ });
402
+ rb_self.owe(ruby, displaced);
403
+ // What the checkin left to do takes Ruby calls, which would overwrite
404
+ // a break, throw or Thread#kill under way; the next settle, on any
405
+ // thread, or a waiting checkout's rescan does it then.
406
+ match &result {
407
+ Err(error) if jumped(error) => result,
408
+ _ => rb_self.settle(ruby, rb_self).and(result),
409
+ }
410
+ }
411
+
412
+ fn nested(ruby: &Ruby, slot: &Slot) -> Result<Value, Error> {
413
+ let context = slot
414
+ .value
415
+ .get(ruby)
416
+ .ok_or_else(|| errors::internal(ruby, "the checked-out context is missing"))?;
417
+ let epoch = fork::epoch();
418
+ rb_raw::yield_ensuring(ruby, context, &mut |ruby, raised| {
419
+ if fork::epoch() == epoch
420
+ && raised.is_some_and(|exception| errors::spends_context(ruby, exception))
421
+ {
422
+ slot.spent.set(true);
423
+ }
424
+ })
425
+ }
426
+
427
+ // Once a slot is marked in use, nothing calls a Ruby method before the
428
+ // block's ensure is in place, so no interrupt can strand the slot.
429
+ // Also the queue of a wait this checkout displaced, which its caller
430
+ // wakes once the checkout is over.
431
+ fn checkout(
432
+ &self,
433
+ ruby: &Ruby,
434
+ rb_self: Obj<Self>,
435
+ fiber: Value,
436
+ ) -> Result<(usize, Value, Option<Value>), Error> {
437
+ self.start_pending(ruby, rb_self)?;
438
+ if self.waiting.borrow().is_empty() {
439
+ let slots = self.slots(ruby)?;
440
+ if let Some(index) = slots
441
+ .iter()
442
+ .position(|slot| slot.phase.get() == Phase::Failed)
443
+ {
444
+ return Err(self.failed(ruby, rb_self, index));
445
+ }
446
+ if let Some(index) = slots
447
+ .iter()
448
+ .position(|slot| slot.phase.get() == Phase::Idle)
449
+ {
450
+ let (index, context) = self.take(ruby, index, fiber)?;
451
+ return Ok((index, context, None));
452
+ }
453
+ }
454
+ // A trap handler or a finalizer that checks out while its own fiber
455
+ // waits here takes that wait's place in line, and any context
456
+ // reserved for it: the wait cannot go on until the handler returns,
457
+ // and then finds its place gone and takes a new one. The handler
458
+ // waits on a queue of its own, so the wait's stays as it slept on it.
459
+ let displaced = self.place_of(ruby, fiber);
460
+ if let Some((index, _)) = displaced.and_then(|outer| self.reserved_for(ruby, outer)) {
461
+ let (index, context) = self.take(ruby, index, fiber)?;
462
+ return Ok((index, context, displaced));
463
+ }
464
+ let queue = thread_queue(ruby)?;
465
+ match displaced {
466
+ Some(outer) => self.replace_waiting(ruby, outer, queue),
467
+ None => self.enlist(ruby, queue, fiber),
468
+ }
469
+ let waited = self.wait_in_turn(ruby, rb_self, fiber, queue);
470
+ // A context handed to this checkout that it did not take goes to the
471
+ // next in line, unless a break, throw or Thread#kill is under way,
472
+ // when the others' rescans find it.
473
+ let handed_back = self.leave(ruby, queue);
474
+ if waited.is_err() {
475
+ self.owe(ruby, displaced);
476
+ }
477
+ match waited {
478
+ Err(error) if jumped(&error) => Err(error),
479
+ Err(error) if handed_back || displaced.is_some() => {
480
+ Err(self.settle(ruby, rb_self).err().unwrap_or(error))
481
+ }
482
+ waited => waited.map(|(index, context)| (index, context, displaced)),
483
+ }
484
+ }
485
+
486
+ fn owe(&self, ruby: &Ruby, displaced: Option<Value>) {
487
+ if let Some(queue) = displaced {
488
+ let root = OwnedRoot::default();
489
+ root.set(ruby, queue);
490
+ self.owed.borrow_mut().push(root);
491
+ }
492
+ }
493
+
494
+ // A displaced wait sleeps in a timed pop, which misses a push made while
495
+ // a trap handler runs on its thread, since the handler's return puts the
496
+ // thread back to sleep; so a thread of the pool's own pushes, once the
497
+ // GVL is free.
498
+ fn wake_owed(&self, ruby: &Ruby) -> Result<(), Error> {
499
+ let count = self.owed.borrow().len();
500
+ if count == 0 {
501
+ return Ok(());
502
+ }
503
+ // The queues stay rooted in `owed` until the array holds them: making
504
+ // and filling it can collect, and a wait that has ended leaves its
505
+ // queue referenced by nothing else. The mark shares this borrow.
506
+ let queues = ruby.ary_new_capa(count);
507
+ for queue in self.owed.borrow().iter() {
508
+ if let Some(queue) = queue.get(ruby) {
509
+ queues.push(queue)?;
510
+ }
511
+ }
512
+ self.owed.borrow_mut().clear();
513
+ gc_root::spawn(ruby, queues, |_ruby, queues: RArray| {
514
+ while let Ok(Some(queue)) = queues.shift::<Option<Value>>() {
515
+ let _ = queue.funcall::<_, _, Value>("push", (true,));
516
+ }
517
+ })
518
+ }
519
+
520
+ fn wait_in_turn(
521
+ &self,
522
+ ruby: &Ruby,
523
+ rb_self: Obj<Self>,
524
+ fiber: Value,
525
+ queue: Value,
526
+ ) -> Result<(usize, Value), Error> {
527
+ loop {
528
+ self.reconcile(ruby);
529
+ self.refuse_if_shut_down(ruby)?;
530
+ if self.reserved_for(ruby, queue).is_none() && !self.is_listed(ruby, queue) {
531
+ self.enlist(ruby, queue, fiber);
532
+ }
533
+ self.start_pending(ruby, rb_self)?;
534
+ self.hand_off(ruby)?;
535
+ if let Some((index, _)) = self.reserved_for(ruby, queue) {
536
+ return self.take(ruby, index, fiber);
537
+ }
538
+ if self
539
+ .first_waiting(ruby)
540
+ .is_some_and(|(first, _)| same(first, queue))
541
+ && let Some(index) = self
542
+ .slots(ruby)?
543
+ .iter()
544
+ .position(|slot| slot.phase.get() == Phase::Failed)
545
+ {
546
+ return Err(self.failed(ruby, rb_self, index));
547
+ }
548
+ queue.funcall::<_, _, Value>("pop", (kwargs!("timeout" => RESCAN_SECONDS),))?;
549
+ }
550
+ }
551
+
552
+ fn is_listed(&self, ruby: &Ruby, queue: Value) -> bool {
553
+ self.waiting.borrow().iter().any(|waiter| {
554
+ waiter
555
+ .queue
556
+ .get(ruby)
557
+ .is_some_and(|listed| same(listed, queue))
558
+ })
559
+ }
560
+
561
+ // Makes no Ruby call. Whether it gave back a context handed to it.
562
+ fn leave(&self, ruby: &Ruby, queue: Value) -> bool {
563
+ self.delist(ruby, queue);
564
+ let Some((_, slot)) = self.reserved_for(ruby, queue) else {
565
+ return false;
566
+ };
567
+ slot.holder.take(ruby);
568
+ slot.waiter.take(ruby);
569
+ slot.phase.set(Phase::Idle);
570
+ true
571
+ }
572
+
573
+ // Gives each free context to the first waiting checkout and wakes it; a
574
+ // failed build wakes the first to raise it.
575
+ fn hand_off(&self, ruby: &Ruby) -> Result<(), Error> {
576
+ if self.shut_down.get() {
577
+ return Ok(());
578
+ }
579
+ let slots = self.slots(ruby)?;
580
+ while let Some((first, fiber)) = self.first_waiting(ruby) {
581
+ if let Some(slot) = slots.iter().find(|slot| slot.phase.get() == Phase::Idle) {
582
+ self.delist(ruby, first);
583
+ slot.holder.set(ruby, first);
584
+ slot.waiter.set(ruby, fiber);
585
+ slot.phase.set(Phase::Reserved);
586
+ } else if !slots.iter().any(|slot| slot.phase.get() == Phase::Failed) {
587
+ return Ok(());
588
+ }
589
+ first.funcall::<_, _, Value>("push", (true,))?;
590
+ if slots.iter().any(|slot| slot.phase.get() == Phase::Failed) {
591
+ return Ok(());
592
+ }
593
+ }
594
+ Ok(())
595
+ }
596
+
597
+ fn take(&self, ruby: &Ruby, index: usize, fiber: Value) -> Result<(usize, Value), Error> {
598
+ let slot = self.slot(index).ok_or_else(|| uninitialized(ruby))?;
599
+ let context = slot
600
+ .value
601
+ .get(ruby)
602
+ .ok_or_else(|| errors::internal(ruby, "the pool's context is missing"))?;
603
+ slot.phase.set(Phase::InUse);
604
+ slot.holder.set(ruby, fiber);
605
+ slot.waiter.take(ruby);
606
+ slot.uses.set(slot.uses.get().saturating_add(1));
607
+ slot.spent.set(false);
608
+ Ok((index, context))
609
+ }
610
+
611
+ // A failed build is raised to the checkout that finds it, after another
612
+ // is started.
613
+ fn failed(&self, ruby: &Ruby, rb_self: Obj<Self>, index: usize) -> Error {
614
+ let raised = self
615
+ .slot(index)
616
+ .and_then(|slot| slot.value.take(ruby))
617
+ .and_then(Exception::from_value);
618
+ if let Some(slot) = self.slot(index) {
619
+ slot.phase.set(Phase::Pending);
620
+ }
621
+ if let Err(error) = self.start_pending(ruby, rb_self) {
622
+ return error;
623
+ }
624
+ raised.map_or_else(
625
+ || errors::internal(ruby, "a pool context failed to build"),
626
+ Error::from,
627
+ )
628
+ }
629
+
630
+ // Runs inside the ensure of the checkout's block, where a Ruby method
631
+ // call could take an interrupt that nothing would then raise, so it only
632
+ // marks the slot; `settle` does the rest.
633
+ fn checkin(&self, ruby: &Ruby, index: usize, epoch: u64, raised: Option<Exception>) {
634
+ // A forked child forgets what its parent checked out.
635
+ if fork::epoch() != epoch {
636
+ return;
637
+ }
638
+ let Some(slot) = self.slot(index) else {
639
+ return;
640
+ };
641
+ if slot.phase.get() != Phase::InUse {
642
+ return;
643
+ }
644
+ slot.holder.take(ruby);
645
+ let spent = slot.spent.get()
646
+ || raised.is_some_and(|exception| errors::spends_context(ruby, exception))
647
+ || slot
648
+ .value
649
+ .get(ruby)
650
+ .is_none_or(|value| context::is_disposed(ruby, value))
651
+ || self
652
+ .max_uses
653
+ .get()
654
+ .is_some_and(|max| slot.uses.get() >= max);
655
+ slot.phase.set(if spent || self.shut_down.get() {
656
+ Phase::Pending
657
+ } else {
658
+ Phase::Idle
659
+ });
660
+ }
661
+
662
+ // Starts the threads pending slots wait for, or after shutdown disposes
663
+ // their contexts here, then hands what is free to waiting checkouts.
664
+ fn settle(&self, ruby: &Ruby, rb_self: Obj<Self>) -> Result<(), Error> {
665
+ self.reconcile(ruby);
666
+ self.start_pending(ruby, rb_self)?;
667
+ self.hand_off(ruby)?;
668
+ self.wake_owed(ruby)
669
+ }
670
+
671
+ fn start_pending(&self, ruby: &Ruby, rb_self: Obj<Self>) -> Result<(), Error> {
672
+ let slots = self.slots(ruby)?;
673
+ let mut failed: Option<Error> = None;
674
+ for (index, slot) in slots.iter().enumerate() {
675
+ if slot.phase.get() != Phase::Pending || failed.as_ref().is_some_and(jumped) {
676
+ continue;
677
+ }
678
+ let started = if self.shut_down.get() {
679
+ slot.phase.set(Phase::Closed);
680
+ slot.value.take(ruby).map_or(Ok(()), dispose)
681
+ } else {
682
+ self.start(ruby, rb_self, index)
683
+ };
684
+ if let Err(error) = started {
685
+ failed.get_or_insert(error);
686
+ }
687
+ }
688
+ failed.map_or(Ok(()), Err)
689
+ }
690
+
691
+ // Replacements are built on a thread of the pool's own, off the request
692
+ // path: it waits on the runners with the GVL released, and a fork leaves
693
+ // it behind, so a child rebuilds whatever its parent's threads were
694
+ // building.
695
+ fn start(&self, ruby: &Ruby, rb_self: Obj<Self>, index: usize) -> Result<(), Error> {
696
+ let Some(slot) = self.slot(index) else {
697
+ return Ok(());
698
+ };
699
+ slot.phase.set(Phase::Building);
700
+ let spawned = gc_root::spawn(ruby, rb_self, move |ruby, pool: Obj<Self>| {
701
+ pool.replace(ruby, pool, index);
702
+ });
703
+ let Err(error) = spawned else {
704
+ return Ok(());
705
+ };
706
+ let refused = match error.error_type() {
707
+ ErrorType::Exception(exception)
708
+ if exception.is_kind_of(ruby.exception_thread_error()) =>
709
+ {
710
+ Some(*exception)
711
+ }
712
+ _ => None,
713
+ };
714
+ let Some(refused) = refused else {
715
+ // An interrupt raised while the thread was made; the slot waits
716
+ // for the next checkout.
717
+ slot.phase.set(Phase::Pending);
718
+ return Err(error);
719
+ };
720
+ // Ruby could not start a thread: the next checkout raises why, after
721
+ // the retired context, if any, is disposed here.
722
+ let retired = slot.value.take(ruby);
723
+ slot.value.set(ruby, refused.as_value());
724
+ slot.phase.set(Phase::Failed);
725
+ retired.map_or(Ok(()), dispose)
726
+ }
727
+
728
+ // On the pool's thread: dispose what the slot retired, then build its
729
+ // replacement unless the pool has shut down meanwhile. A thread killed
730
+ // midway leaves the slot pending for the next checkout.
731
+ fn replace(&self, ruby: &Ruby, rb_self: Obj<Self>, index: usize) {
732
+ let Some(slot) = self.slot(index) else {
733
+ return;
734
+ };
735
+ if let Some(retired) = slot.value.take(ruby)
736
+ && dispose(retired).is_err_and(|error| jumped(&error))
737
+ {
738
+ slot.phase.set(Phase::Pending);
739
+ return;
740
+ }
741
+ if self.shut_down.get() {
742
+ slot.phase.set(Phase::Closed);
743
+ return;
744
+ }
745
+ let built = self.build(ruby);
746
+ if self.shut_down.get() {
747
+ slot.phase.set(Phase::Closed);
748
+ if let Ok(context) = built {
749
+ let _ = dispose(context);
750
+ }
751
+ return;
752
+ }
753
+ match built {
754
+ Ok(context) => {
755
+ slot.value.set(ruby, context);
756
+ slot.uses.set(0);
757
+ slot.phase.set(Phase::Idle);
758
+ }
759
+ Err(error) => {
760
+ if let ErrorType::Exception(exception) = error.error_type() {
761
+ slot.value.set(ruby, exception.as_value());
762
+ slot.phase.set(Phase::Failed);
763
+ } else {
764
+ slot.phase.set(Phase::Pending);
765
+ return;
766
+ }
767
+ }
768
+ }
769
+ let _ = self.settle(ruby, rb_self);
770
+ }
771
+
772
+ // Idle contexts, and retired ones not yet disposed, are disposed now;
773
+ // those in use when their checkout ends, and those being built once built.
774
+ fn shutdown(ruby: &Ruby, rb_self: Obj<Self>) -> Result<(), Error> {
775
+ let slots = rb_self.slots(ruby)?;
776
+ rb_self.reconcile(ruby);
777
+ // Called again, it finishes disposing what an interrupt stopped.
778
+ if !rb_self.shut_down.replace(true) {
779
+ for slot in slots {
780
+ match slot.phase.get() {
781
+ Phase::Idle | Phase::Reserved => {
782
+ slot.holder.take(ruby);
783
+ slot.waiter.take(ruby);
784
+ slot.phase.set(Phase::Pending);
785
+ }
786
+ Phase::Failed => {
787
+ slot.value.take(ruby);
788
+ slot.phase.set(Phase::Closed);
789
+ }
790
+ Phase::Pending | Phase::Building | Phase::InUse | Phase::Closed => {}
791
+ }
792
+ }
793
+ }
794
+ let waiting: Vec<Value> = rb_self
795
+ .waiting
796
+ .borrow()
797
+ .iter()
798
+ .filter_map(|waiter| waiter.queue.get(ruby))
799
+ .collect();
800
+ for queue in waiting {
801
+ queue.funcall::<_, _, Value>("push", (true,))?;
802
+ }
803
+ rb_self.wake_owed(ruby)?;
804
+ rb_self.start_pending(ruby, rb_self)
805
+ }
806
+ }
807
+
808
+ // By identity; both values are pinned, by the pool's mark or this stack.
809
+ fn same(left: Value, right: Value) -> bool {
810
+ rb_raw::identity(left) == rb_raw::identity(right)
811
+ }